mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-04-30 03:40:34 +02:00
Code Activity

Promote subsections inside the GOOPS "Reference Manual" section

Browse source 
* doc/ref/goops.texi (Reference Manual): Node deleted, with content
  promoted up to...

* doc/ref/goops.texi (GOOPS): ...here.
This commit is contained in:
Neil Jerram 2010-09-25 15:19:30 +01:00
parent 23295dc35c
commit c34d74fffd
1 changed files with 54 additions and 72 deletions
Download patch file Download diff file Expand all files Collapse all files

126
doc/ref/goops.texi
View file

@ -32,7 +32,17 @@ overriding or redefining those methods.
* Copyright Notice:: * Copyright Notice::
* Quick Start:: * Quick Start::
* Tutorial:: * Tutorial::
* Reference Manual:: * Introductory Remarks::
* Defining New Classes::
* Creating Instances::
* Accessing Slots::
* Creating Generic Functions::
* Adding Methods to Generic Functions::
* Invoking Generic Functions::
* Redefining a Class::
* Changing the Class of an Instance::
* Introspection::
* Miscellaneous Functions::
* MOP Specification:: * MOP Specification::
@end menu @end menu
@ -182,36 +192,8 @@ objects, to add two of them together:
@section Tutorial @section Tutorial
@include goops-tutorial.texi @include goops-tutorial.texi
@node Reference Manual
@section Reference Manual
This chapter is the GOOPS reference manual. It aims to describe all the
syntax, procedures, options and associated concepts that a typical
application author would need to understand in order to use GOOPS
effectively in their application. It also describes what is meant by
the GOOPS ``metaobject protocol'' (aka ``MOP''), and indicates how
authors can use the metaobject protocol to customize the behaviour of
GOOPS itself.
For a detailed specification of the GOOPS metaobject protocol, see
@ref{MOP Specification}.
@menu
* Introductory Remarks::
* Defining New Classes::
* Creating Instances::
* Accessing Slots::
* Creating Generic Functions::
* Adding Methods to Generic Functions::
* Invoking Generic Functions::
* Redefining a Class::
* Changing the Class of an Instance::
* Introspection::
* Miscellaneous Functions::
@end menu
@node Introductory Remarks @node Introductory Remarks
@subsection Introductory Remarks @section Introductory Remarks
GOOPS is an object-oriented programming system based on a ``metaobject GOOPS is an object-oriented programming system based on a ``metaobject
protocol'' derived from the ones used in CLOS (the Common Lisp Object protocol'' derived from the ones used in CLOS (the Common Lisp Object
@ -252,7 +234,7 @@ provides definitions for these terms.
@end menu @end menu
@node Metaobjects and the Metaobject Protocol @node Metaobjects and the Metaobject Protocol
@subsubsection Metaobjects and the Metaobject Protocol @subsection Metaobjects and the Metaobject Protocol
The conceptual building blocks of GOOPS are classes, slot definitions, The conceptual building blocks of GOOPS are classes, slot definitions,
instances, generic functions and methods. A class is a grouping of instances, generic functions and methods. A class is a grouping of
@ -362,7 +344,7 @@ class names), but it is worth noting that GOOPS conforms fully to this
Schemely principle. Schemely principle.
@node Terminology @node Terminology
@subsubsection Terminology @subsection Terminology
It is assumed that the reader is already familiar with standard object It is assumed that the reader is already familiar with standard object
orientation concepts such as classes, objects/instances, orientation concepts such as classes, objects/instances,
@ -544,7 +526,7 @@ be invoked using the generalized @code{set!} syntax, as in:
@end example @end example
@node Defining New Classes @node Defining New Classes
@subsection Defining New Classes @section Defining New Classes
[ *fixme* Somewhere in this manual there needs to be an introductory [ *fixme* Somewhere in this manual there needs to be an introductory
discussion about GOOPS classes, generic functions and methods, covering discussion about GOOPS classes, generic functions and methods, covering
@ -583,7 +565,7 @@ the discussion there. ]
@end menu @end menu
@node Basic Class Definition @node Basic Class Definition
@subsubsection Basic Class Definition @subsection Basic Class Definition
New classes are defined using the @code{define-class} syntax, with New classes are defined using the @code{define-class} syntax, with
arguments that specify the classes that the new class should inherit arguments that specify the classes that the new class should inherit
@ -642,7 +624,7 @@ customized via an application-defined metaclass.
@end example @end example
@node Class Options @node Class Options
@subsubsection Class Options @subsection Class Options
@deffn {class option} #:metaclass metaclass @deffn {class option} #:metaclass metaclass
The @code{#:metaclass} class option specifies the metaclass of the class The @code{#:metaclass} class option specifies the metaclass of the class
@ -675,7 +657,7 @@ environment defaults to the top-level environment in which the
@end deffn @end deffn
@node Slot Options @node Slot Options
@subsubsection Slot Options @subsection Slot Options
@deffn {slot option} #:allocation allocation @deffn {slot option} #:allocation allocation
The @code{#:allocation} option tells GOOPS how to allocate storage for The @code{#:allocation} option tells GOOPS how to allocate storage for
@ -878,7 +860,7 @@ classes.
@end deffn @end deffn
@node Class Definition Internals @node Class Definition Internals
@subsubsection Class Definition Internals @subsection Class Definition Internals
Implementation notes: @code{define-class} expands to an expression which Implementation notes: @code{define-class} expands to an expression which
@ -991,7 +973,7 @@ class object, are described in @ref{Customizing Instance Creation},
which covers the creation and initialization of instances in general. which covers the creation and initialization of instances in general.
@node Customizing Class Definition @node Customizing Class Definition
@subsubsection Customizing Class Definition @subsection Customizing Class Definition
During the initialization of a new class, GOOPS calls a number of generic During the initialization of a new class, GOOPS calls a number of generic
functions with the newly allocated class instance as the first functions with the newly allocated class instance as the first
@ -1127,7 +1109,7 @@ typically it would perform additional class initialization steps before
and/or after calling @code{(next-method)} for the standard behaviour. and/or after calling @code{(next-method)} for the standard behaviour.
@node STKlos Compatibility @node STKlos Compatibility
@subsubsection STKlos Compatibility @subsection STKlos Compatibility
If the STKlos compatibility module is loaded, @code{define-class} is If the STKlos compatibility module is loaded, @code{define-class} is
overwritten by a STKlos-specific definition; the standard GOOPS overwritten by a STKlos-specific definition; the standard GOOPS
@ -1140,7 +1122,7 @@ definition of @code{define-class} remains available in
@end deffn @end deffn
@node Creating Instances @node Creating Instances
@subsection Creating Instances @section Creating Instances
@menu @menu
* Basic Instance Creation:: * Basic Instance Creation::
@ -1148,7 +1130,7 @@ definition of @code{define-class} remains available in
@end menu @end menu
@node Basic Instance Creation @node Basic Instance Creation
@subsubsection Basic Instance Creation @subsection Basic Instance Creation
To create a new instance of any GOOPS class, use the generic function To create a new instance of any GOOPS class, use the generic function
@code{make} or @code{make-instance}, passing the required class and any @code{make} or @code{make-instance}, passing the required class and any
@ -1185,7 +1167,7 @@ instance's class. Any unprocessed keyword value pairs are ignored.
@end deffn @end deffn
@node Customizing Instance Creation @node Customizing Instance Creation
@subsubsection Customizing Instance Creation @subsection Customizing Instance Creation
@code{make} itself is a generic function. Hence the @code{make} @code{make} itself is a generic function. Hence the @code{make}
invocation itself can be customized in the case where the new instance's invocation itself can be customized in the case where the new instance's
@ -1252,7 +1234,7 @@ and closures in the slot definitions, it is neater to write an
and initializes all the dependent slot values according to the results. and initializes all the dependent slot values according to the results.
@node Accessing Slots @node Accessing Slots
@subsection Accessing Slots @section Accessing Slots
The definition of a slot contains at the very least a slot name, and may The definition of a slot contains at the very least a slot name, and may
also contain various slot options, including getter, setter and/or also contain various slot options, including getter, setter and/or
@ -1316,7 +1298,7 @@ closures, see @ref{Customizing Class Definition,, compute-get-n-set}.)
@end menu @end menu
@node Instance Slots @node Instance Slots
@subsubsection Instance Slots @subsection Instance Slots
Any slot, regardless of its allocation, can be queried, referenced and Any slot, regardless of its allocation, can be queried, referenced and
set using the following four primitive procedures. set using the following four primitive procedures.
@ -1413,7 +1395,7 @@ slot-missing}).
@end deffn @end deffn
@node Class Slots @node Class Slots
@subsubsection Class Slots @subsection Class Slots
Slots whose allocation is per-class rather than per-instance can be Slots whose allocation is per-class rather than per-instance can be
referenced and set without needing to specify any particular instance. referenced and set without needing to specify any particular instance.
@ -1441,7 +1423,7 @@ function with arguments @var{class} and @var{slot-name}.
@end deffn @end deffn
@node Handling Slot Access Errors @node Handling Slot Access Errors
@subsubsection Handling Slot Access Errors @subsection Handling Slot Access Errors
GOOPS calls one of the following generic functions when a ``slot-ref'' GOOPS calls one of the following generic functions when a ``slot-ref''
or ``slot-set!'' call specifies a non-existent slot name, or tries to or ``slot-set!'' call specifies a non-existent slot name, or tries to
@ -1472,7 +1454,7 @@ message.
@end deffn @end deffn
@node Creating Generic Functions @node Creating Generic Functions
@subsection Creating Generic Functions @section Creating Generic Functions
A generic function is a collection of methods, with rules for A generic function is a collection of methods, with rules for
determining which of the methods should be applied for any given determining which of the methods should be applied for any given
@ -1488,7 +1470,7 @@ GOOPS represents generic functions as metaobjects of the class
@end menu @end menu
@node Basic Generic Function Creation @node Basic Generic Function Creation
@subsubsection Basic Generic Function Creation @subsection Basic Generic Function Creation
The following forms may be used to bind a variable to a generic The following forms may be used to bind a variable to a generic
function. Depending on that variable's pre-existing value, the generic function. Depending on that variable's pre-existing value, the generic
@ -1598,7 +1580,7 @@ form of the @code{#:duplicates} option can be used instead:
@end lisp @end lisp
@node Generic Function Internals @node Generic Function Internals
@subsubsection Generic Function Internals @subsection Generic Function Internals
@code{define-generic} calls @code{ensure-generic} to upgrade a @code{define-generic} calls @code{ensure-generic} to upgrade a
pre-existing procedure value, or @code{make} with metaclass pre-existing procedure value, or @code{make} with metaclass
@ -1667,7 +1649,7 @@ accessor, passing the setter generic function as the value of the
@code{#:setter} keyword. @code{#:setter} keyword.
@node Extending Guiles Primitives @node Extending Guiles Primitives
@subsubsection Extending Guile's Primitives @subsection Extending Guile's Primitives
When GOOPS is loaded, many of Guile's primitive procedures can be When GOOPS is loaded, many of Guile's primitive procedures can be
extended by giving them a generic function definition that operates extended by giving them a generic function definition that operates
@ -1714,7 +1696,7 @@ integrated into the core of Guile. Consequently, the
procedures described in this section may disappear as well. procedures described in this section may disappear as well.
@node Adding Methods to Generic Functions @node Adding Methods to Generic Functions
@subsection Adding Methods to Generic Functions @section Adding Methods to Generic Functions
@menu @menu
* Basic Method Definition:: * Basic Method Definition::
@ -1722,7 +1704,7 @@ procedures described in this section may disappear as well.
@end menu @end menu
@node Basic Method Definition @node Basic Method Definition
@subsubsection Basic Method Definition @subsection Basic Method Definition
To add a method to a generic function, use the @code{define-method} form. To add a method to a generic function, use the @code{define-method} form.
@ -1781,7 +1763,7 @@ invocation error handling, and generic function invocation in general,
see @ref{Invoking Generic Functions}. see @ref{Invoking Generic Functions}.
@node Method Definition Internals @node Method Definition Internals
@subsubsection Method Definition Internals @subsection Method Definition Internals
@code{define-method} @code{define-method}
@ -1868,7 +1850,7 @@ function.
@end deffn @end deffn
@node Invoking Generic Functions @node Invoking Generic Functions
@subsection Invoking Generic Functions @section Invoking Generic Functions
When a variable with a generic function definition appears as the first When a variable with a generic function definition appears as the first
element of a list that is being evaluated, the Guile evaluator tries element of a list that is being evaluated, the Guile evaluator tries
@ -1890,7 +1872,7 @@ may be applied subsequently if a method that is being applied calls
@end menu @end menu
@node Determining Which Methods to Apply @node Determining Which Methods to Apply
@subsubsection Determining Which Methods to Apply @subsection Determining Which Methods to Apply
[ *fixme* Sorry - this is the area of GOOPS that I understand least of [ *fixme* Sorry - this is the area of GOOPS that I understand least of
all, so I'm afraid I have to pass on this section. Would some other all, so I'm afraid I have to pass on this section. Would some other
@ -1921,7 +1903,7 @@ kind person consider filling it in? ]
@end deffn @end deffn
@node Handling Invocation Errors @node Handling Invocation Errors
@subsubsection Handling Invocation Errors @subsection Handling Invocation Errors
@deffn generic no-method @deffn generic no-method
@deffnx method no-method (gf <generic>) args @deffnx method no-method (gf <generic>) args
@ -1949,7 +1931,7 @@ default method calls @code{goops-error} with an appropriate message.
@end deffn @end deffn
@node Redefining a Class @node Redefining a Class
@subsection Redefining a Class @section Redefining a Class
Suppose that a class @code{<my-class>} is defined using @code{define-class} Suppose that a class @code{<my-class>} is defined using @code{define-class}
(@pxref{Basic Class Definition,, define-class}), with slots that have (@pxref{Basic Class Definition,, define-class}), with slots that have
@ -1964,7 +1946,7 @@ make}). What then happens if @code{<my-class>} is redefined by calling
@end menu @end menu
@node Default Class Redefinition Behaviour @node Default Class Redefinition Behaviour
@subsubsection Default Class Redefinition Behaviour @subsection Default Class Redefinition Behaviour
GOOPS' default answer to this question is as follows. GOOPS' default answer to this question is as follows.
@ -2017,7 +1999,7 @@ Also bear in mind that, like most of GOOPS' default behaviour, it can
be customized@dots{} be customized@dots{}
@node Customizing Class Redefinition @node Customizing Class Redefinition
@subsubsection Customizing Class Redefinition @subsection Customizing Class Redefinition
When @code{define-class} notices that a class is being redefined, When @code{define-class} notices that a class is being redefined,
it constructs the new class metaobject as usual, and then invokes the it constructs the new class metaobject as usual, and then invokes the
@ -2082,7 +2064,7 @@ generic functions, and so on@dots{} The detailed protocol for all of these
is described in @ref{MOP Specification}. is described in @ref{MOP Specification}.
@node Changing the Class of an Instance @node Changing the Class of an Instance
@subsection Changing the Class of an Instance @section Changing the Class of an Instance
You can change the class of an existing instance by invoking the You can change the class of an existing instance by invoking the
generic function @code{change-class} with two arguments: the instance generic function @code{change-class} with two arguments: the instance
@ -2121,7 +2103,7 @@ invokes the @code{change-class} generic function for each existing
instance of the redefined class. instance of the redefined class.
@node Introspection @node Introspection
@subsection Introspection @section Introspection
@dfn{Introspection}, also known as @dfn{reflection}, is the name given @dfn{Introspection}, also known as @dfn{reflection}, is the name given
to the ability to obtain information dynamically about GOOPS metaobjects. to the ability to obtain information dynamically about GOOPS metaobjects.
@ -2160,7 +2142,7 @@ GOOPS equivalents --- to be obtained dynamically, at run time.
@end menu @end menu
@node Classes @node Classes
@subsubsection Classes @subsection Classes
@deffn {primitive procedure} class-name class @deffn {primitive procedure} class-name class
Return the name of class @var{class}. Return the name of class @var{class}.
@ -2220,7 +2202,7 @@ Return a list of all methods that use @var{class} or a subclass of
@end deffn @end deffn
@node Slots @node Slots
@subsubsection Slots @subsection Slots
@deffn procedure class-slot-definition class slot-name @deffn procedure class-slot-definition class slot-name
Return the slot definition for the slot named @var{slot-name} in class Return the slot definition for the slot named @var{slot-name} in class
@ -2301,7 +2283,7 @@ see @ref{Slot Options,, init-value}.
@end deffn @end deffn
@node Instances @node Instances
@subsubsection Instances @subsection Instances
@deffn {primitive procedure} class-of value @deffn {primitive procedure} class-of value
Return the GOOPS class of any Scheme @var{value}. Return the GOOPS class of any Scheme @var{value}.
@ -2322,7 +2304,7 @@ Implementation notes: @code{is-a?} uses @code{class-of} and
@var{object}. @var{object}.
@node Generic Functions @node Generic Functions
@subsubsection Generic Functions @subsection Generic Functions
@deffn {primitive procedure} generic-function-name gf @deffn {primitive procedure} generic-function-name gf
Return the name of generic function @var{gf}. Return the name of generic function @var{gf}.
@ -2334,7 +2316,7 @@ This is the value of the @var{gf} metaobject's @code{methods} slot.
@end deffn @end deffn
@node Generic Function Methods @node Generic Function Methods
@subsubsection Generic Function Methods @subsection Generic Function Methods
@deffn {primitive procedure} method-generic-function method @deffn {primitive procedure} method-generic-function method
Return the generic function that @var{method} belongs to. Return the generic function that @var{method} belongs to.
@ -2372,7 +2354,7 @@ Return an expression that prints to show the definition of method
@end deffn @end deffn
@node Miscellaneous Functions @node Miscellaneous Functions
@subsection Miscellaneous Functions @section Miscellaneous Functions
@menu @menu
* Administrative Functions:: * Administrative Functions::
@ -2383,7 +2365,7 @@ Return an expression that prints to show the definition of method
@end menu @end menu
@node Administrative Functions @node Administrative Functions
@subsubsection Administration Functions @subsection Administration Functions
This section describes administrative, non-technical GOOPS functions. This section describes administrative, non-technical GOOPS functions.
@ -2392,7 +2374,7 @@ Return the current GOOPS version as a string, for example ``0.2''.
@end deffn @end deffn
@node GOOPS Error Handling @node GOOPS Error Handling
@subsubsection Error Handling @subsection Error Handling
The procedure @code{goops-error} is called to raise an appropriate error The procedure @code{goops-error} is called to raise an appropriate error
by the default methods of the following generic functions: by the default methods of the following generic functions:
@ -2427,7 +2409,7 @@ as done by @code{scm-error}.
@end deffn @end deffn
@node Object Comparisons @node Object Comparisons
@subsubsection Object Comparisons @subsection Object Comparisons
@deffn generic eqv? @deffn generic eqv?
@deffnx method eqv? ((x <top>) (y <top>)) @deffnx method eqv? ((x <top>) (y <top>))
@ -2456,7 +2438,7 @@ and the Guile reference manual.
@end deffn @end deffn
@node Cloning Objects @node Cloning Objects
@subsubsection Cloning Objects @subsection Cloning Objects
@deffn generic shallow-clone @deffn generic shallow-clone
@deffnx method shallow-clone (self <object>) @deffnx method shallow-clone (self <object>)
@ -2477,7 +2459,7 @@ or by reference.
@end deffn @end deffn
@node Write and Display @node Write and Display
@subsubsection Write and Display @subsection Write and Display
@deffn {primitive generic} write object port @deffn {primitive generic} write object port
@deffnx {primitive generic} display object port @deffnx {primitive generic} display object port