[Guile-commits] GNU Guile branch, master, updated. release_1-9-12-48-g5a6c9e7

[Neil Jerram]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Guile".

http://git.savannah.gnu.org/cgit/guile.git/commit/?id=5a6c9e7593c664b692c35191798f4e0881cf35de

The branch, master has been updated
       via  5a6c9e7593c664b692c35191798f4e0881cf35de (commit)
       via  5268eca68691d21f6aacd7eebe709cac8a07f04c (commit)
       via  de69bd28e3656397fa436c3841ccc7db9744992f (commit)
       via  b65ff721a65aa3d7d1f0821d1c2373e257bb7ed3 (commit)
       via  b997e7f517d03b07c2321fcfdd3dd57fe63b63e5 (commit)
      from  d8e2ba23fc30cd705f9e3dacb149cf5395299f5d (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 5a6c9e7593c664b692c35191798f4e0881cf35de
Author: Neil Jerram <address@hidden>
Date:   Wed Sep 22 01:27:31 2010 +0100

    Explain examples of user-defined classes
    
    * doc/ref/goops.texi (User-defined classes): New text added to explain
      the example code.

commit 5268eca68691d21f6aacd7eebe709cac8a07f04c
Author: Neil Jerram <address@hidden>
Date:   Wed Sep 22 00:52:30 2010 +0100

    Explain built-in classes like <string>
    
    * doc/ref/goops.texi (Built-in classes): New node.
      (User-defined classes): Show is-a? v and class-of v here, instead of
      in next node.
      (Asking for the class of an object): Deleted, no longer needed.

commit de69bd28e3656397fa436c3841ccc7db9744992f
Author: Neil Jerram <address@hidden>
Date:   Wed Sep 22 00:20:38 2010 +0100

    Improve GOOPS `Quick Start' doc
    
    * doc/ref/goops.texi (Quick Start): Remove words that only reiterate
      "quick start".
    
    * doc/ref/goops.texi (Methods, User-defined classes, Asking for the
      class of an object): Say "class" instead of "type".  They
      are called classes elsewhere, and in an object-oriented system, people
      expect classes!

commit b65ff721a65aa3d7d1f0821d1c2373e257bb7ed3
Author: Neil Jerram <address@hidden>
Date:   Wed Sep 22 00:15:25 2010 +0100

    Move GOOPS chapter's Stk copyright notice upfront
    
    So as to enable more free refactoring of the rest of the chapter
    
    * doc/ref/goops.texi (Copyright Notice): New section containing the
      Stk copyright.
    
    * doc/ref/goops-tutorial.texi (Copyright): Equivalent section here
      deleted.

commit b997e7f517d03b07c2321fcfdd3dd57fe63b63e5
Author: Neil Jerram <address@hidden>
Date:   Sun Sep 12 21:07:55 2010 +0100

    GOOPS doc simplification
    
    * doc/ref/goops.texi (GOOPS): Simplify the introductory blurb.

-----------------------------------------------------------------------

Summary of changes:
 doc/ref/goops-tutorial.texi |   20 -------
 doc/ref/goops.texi          |  126 +++++++++++++++++++++++++++++++-----------
 2 files changed, 93 insertions(+), 53 deletions(-)

diff --git a/doc/ref/goops-tutorial.texi b/doc/ref/goops-tutorial.texi
index 569920a..76774f8 100644
--- a/doc/ref/goops-tutorial.texi
+++ b/doc/ref/goops-tutorial.texi
@@ -47,7 +47,6 @@ The main @goops{} module is imported by evaluating:
 @cindex preparing
 
 @menu
-* Copyright::
 * Class definition::  
 * Instance creation and slot access::  
 * Slot description::            
@@ -55,25 +54,6 @@ The main @goops{} module is imported by evaluating:
 * Generic functions::           
 @end menu
 
address@hidden Copyright
address@hidden Copyright
-
-Original attribution:
-
-STk Reference manual (Appendix: An Introduction to STklos)
-
-Copyright © 1993-1999 Erick Gallesio - I3S-CNRS/ESSI <eg@@unice.fr>
-Permission to use, copy, modify, distribute,and license this
-software and its documentation for any purpose is hereby granted,
-provided that existing copyright notices are retained in all
-copies and that this notice is included verbatim in any
-distributions.  No written agreement, license, or royalty fee is
-required for any of the authorized uses.
-This software is provided ``AS IS'' without express or implied
-warranty.
-
-Adapted for use in Guile with the author's permission
-
 @node Class definition
 @subsection Class definition
 
diff --git a/doc/ref/goops.texi b/doc/ref/goops.texi
index 9b0d057..7b824c8 100644
--- a/doc/ref/goops.texi
+++ b/doc/ref/goops.texi
@@ -18,30 +18,47 @@ Guile
 @goops{} is the object oriented extension to @guile{}. Its
 implementation is derived from @w{STk-3.99.3} by Erick Gallesio and
 version 1.3 of Gregor Kiczales' @cite{Tiny-Clos}.  It is very close in
-spirit to CLOS, the Common Lisp Object System (@cite{CLtL2}) but is
-adapted for the Scheme language.  While GOOPS is not compatible with any
-of these systems, GOOPS contains a compatibility module which allows for
-execution of STKlos programs.
+spirit to CLOS, the Common Lisp Object System, but is adapted for the
+Scheme language.
 
-Briefly stated, the @goops{} extension gives the user a full object
-oriented system with multiple inheritance and generic functions with
-multi-method dispatch.  Furthermore, the implementation relies on a true
-meta object protocol, in the spirit of the one defined for CLOS
-(@cite{Gregor Kiczales: A Metaobject Protocol}).
address@hidden is a full object oriented system, with classes, objects,
+multiple inheritance, and generic functions with multi-method
+dispatch.  Furthermore its implementation relies on a meta object
+protocol --- which means that @goops{}'s core operations are themselves
+defined as methods on relevant classes, and can be customised by
+overriding or redefining those methods.
 
 @menu
+* Copyright Notice::
 * Quick Start::
 * Tutorial::
 * Reference Manual::
 * MOP Specification::
 @end menu
 
address@hidden Copyright Notice
address@hidden Copyright Notice
+
+The material in this chapter is partly derived from the STk Reference
+Manual written by Erick Gallesio, whose copyright notice is as follows.
+
+Copyright © 1993-1999 Erick Gallesio - I3S-CNRS/ESSI <eg@@unice.fr>
+Permission to use, copy, modify, distribute,and license this
+software and its documentation for any purpose is hereby granted,
+provided that existing copyright notices are retained in all
+copies and that this notice is included verbatim in any
+distributions.  No written agreement, license, or royalty fee is
+required for any of the authorized uses.
+This software is provided ``AS IS'' without express or implied
+warranty.
+
+The material has been adapted for use in Guile, with the author's
+permission.
+
+
 @node Quick Start
 @section Quick Start
 
-To give an immediate flavour of what GOOPS can do, here is a very
-brief introduction to its main operations.
-
 To start using GOOPS, load the @code{(oop goops)} module:
 
 @lisp
@@ -52,15 +69,16 @@ We're now ready to try some basic GOOPS functionality.
 
 @menu
 * Methods::
-* User-defined types::
-* Asking for the type of an object::
+* Built-in classes::
+* User-defined classes::
 @end menu
 
+
 @node Methods
 @subsection Methods
 
 A GOOPS method is like a Scheme procedure except that it is
-specialized for a particular set of argument types.
+specialized for a particular set of argument classes.
 
 @lisp
 (define-method (+ (x <string>) (y <string>))
@@ -70,53 +88,95 @@ specialized for a particular set of argument types.
 @end lisp
 
 If @code{+} is used with arguments that do not match the method's
-types, Guile falls back to using the normal Scheme @code{+} procedure.
+classes, Guile falls back to using the normal Scheme @code{+} procedure.
 
 @lisp
 (+ 1 2) @result{} 3
 @end lisp
 
 
address@hidden User-defined types
address@hidden User-defined types
address@hidden Built-in classes
address@hidden Built-in classes
+
+There are built-in classes like @code{<string>}, @code{<list>} and
address@hidden<number>} corresponding to all the Guile Scheme types.  You can
+use the @code{is-a?} predicate to ask whether any given value belongs to
+a given class, or @code{class-of} to discover the class of a given
+value.
+
address@hidden
+(is-a? 2.3 <number>) @result{} #t
+(is-a? 2.3 <real>) @result{} #t
+(is-a? 2.3 <string>) @result{} #f
+(is-a? '("a" "b") <string>) @result{} #f
+(is-a? '("a" "b") <list>) @result{} #t
+(is-a? (car '("a" "b")) <string>) @result{} #t
+(is-a? <string> <class>) @result{} #t
+(is-a? <class> <string>) @result{} #f
+
+(class-of 2.3) @result{} #<<class> <real> 908c708>
+(class-of #(1 2 3)) @result{} #<<class> <vector> 908cd20>
+(class-of <string>) @result{} #<<class> <class> 8bd3e10>
+(class-of <class>) @result{} #<<class> <class> 8bd3e10>
address@hidden lisp
+
+
address@hidden User-defined classes
address@hidden User-defined classes
+
+You can, of course, also define new classes.  The GOOPS term for
+``fields'' or ``member variables'' is @dfn{slots}, and the main thing
+you have to specify, when defining a new class, is what its slots will
+be, and how they will be initialised and accessed.
 
 @lisp
 (define-class <2D-vector> ()
   (x #:init-value 0 #:accessor x-component #:init-keyword #:x)
   (y #:init-value 0 #:accessor y-component #:init-keyword #:y))
address@hidden lisp
+
+Methods are not (formally) part of a specific class's definition,
+because a single method can be associated with several classes.  If
+you've studied object orientation in non-Lispy languages, you may
+remember discussions such as whether a method to stretch a graphical
+image around a surface should be a method of the image class, with a
+surface as a parameter, or a method of the surface class, with an image
+as a parameter.  In the generic function approach that GOOPS provides,
+this question does not arise.
 
address@hidden
+Here we customise @code{write} for the new class, so that
address@hidden<2D-vector>} objects will be nicely printed:
+
address@hidden
 (use-modules (ice-9 format))
 
 (define-method (write (obj <2D-vector>) port)
   (format port "<~S, ~S>" (x-component obj) (y-component obj)))
address@hidden lisp
+
+To make an @dfn{instance} or @dfn{object} of your new class, use
address@hidden together with the class and any initialisation arguments:
 
address@hidden
 (define v (make <2D-vector> #:x 3 #:y 4))
 
 v @result{} <3, 4>
address@hidden group
+(is-a? v <2D-vector>) @result{} #t
+(class-of v) @result{} #<<class> <2D-vector> 40241ac0>
address@hidden lisp
 
address@hidden
+Here is another method that is specialised for @code{<2D-vector>}
+objects, to add two of them together:
+
address@hidden
 (define-method (+ (x <2D-vector>) (y <2D-vector>))
   (make <2D-vector>
         #:x (+ (x-component x) (x-component y))
         #:y (+ (y-component x) (y-component y))))
 
 (+ v v) @result{} <6, 8>
address@hidden group
 @end lisp
 
address@hidden Asking for the type of an object
address@hidden Types
-
address@hidden
-(class-of v) @result{} #<<class> <2D-vector> 40241ac0>
-<2D-vector>  @result{} #<<class> <2D-vector> 40241ac0>
-(class-of 1) @result{} #<<class> <integer> 401b2a98>
-<integer>    @result{} #<<class> <integer> 401b2a98>
-
-(is-a? v <2D-vector>) @result{} #t
address@hidden example
 
 @node Tutorial
 @section Tutorial


hooks/post-receive
-- 
GNU Guile