This is the mail archive of the guile@sources.redhat.com mailing list for the Guile project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]

Re: struct bug


Mikael Djurfeldt <mdj@mdj.nada.kth.se> writes:

> I'll try to get time later today to update the documentation.  I'll
> then mail Clark, you, and the list.

OK, here it goes.  At least the `make-vtable-vtable' docs is a bit
long for a docstring.  Maybe something can be moved to the manual?

I actually found a bug in simple-format which is invoked by the
example in the docstring.  For those of you who doesn't update your
CVS Guile every ten minutes, you can replace the call to format with
multiple calls to display.

guile> (help make-struct)
(guile): make-struct
(make-struct vtable tail_array_size init)
Create a new structure.

@var{type} must be a vtable structure (@xref{Vtables}).

@var{tail-elts} must be a non-negative integer.  If the layout
specification indicated by @var{type} includes a tail-array,
this is the number of elements allocated to that array.

The @var{init1}, @dots are optional arguments describing how
successive fields of the structure should be initialized.  Only fields
with protection 'r' or 'w' can be initialized, except for fields of
type 's', which are automatically initialized to point to the new
structure itself; fields with protection 'o' can not be initialized by
Scheme programs.

If fewer optional arguments than initializable fields are supplied,
fields of type 'p' get default value #f while fields of type 'u' are
initialized to 0.

Structs are currently the basic representation for record-like data
structures in Guile.  The plan is to eventually replace them with a
new representation which will at the same time be easier to use and
more powerful.

For more information, see the documentation for @code{make-vtable-vtable}.
[../../../guile-core/libguile/struct.c:379]
guile> (help make-vtable-vtable)
(guile): make-vtable-vtable
(make-vtable-vtable user_fields tail_array_size init)
Return a new, self-describing vtable structure.

@var{user-fields} is a string describing user defined fields of the
vtable beginning at index @code{vtable-offset-user}
(see @code{make-struct-layout}).

@var{tail-size} specifies the size of the tail-array (if any) of
this vtable.

@var{init1}, @dots are the optional initializers for the fields of
the vtable.

Vtables have one initializable system field---the struct printer.
This field comes before the user fields in the initializers passed
to @code{make-vtable-vtable} and @code{make-struct}, and thus works as
a third optional argument to @code{make-vtable-vtable} and a fourth to
@code{make-struct} when creating vtables:

If the value is a procedure, it will be called instead of the standard
printer whenever a struct described by this vtable is printed.
The procedure will be called with arguments STRUCT and PORT.

The structure of a struct is described by a vtable, so the vtable is
in essence the type of the struct.  The vtable is itself a struct with
a vtable.  This could go on forever if it weren't for the
vtable-vtables which are self-describing vtables, and thus terminates
the chain.

There are several potential ways of using structs, but the standard
one is to use three kinds of structs, together building up a type
sub-system: one vtable-vtable working as the root and one or several
\"types\", each with a set of \"instances\".  (The vtable-vtable should be
compared to the class <class> which is a class of itself.)

@example
(define ball-root (make-vtable-vtable \"pr\" 0))

(define (make-ball-type ball-color)
  (make-struct ball-root 0
	       (make-struct-layout \"pw\")
               (lambda (ball port)
                 (format port \"#<a ~A ball owned by ~A>"
                         (color ball)
                         (owner ball)))
               ball-color))
(define (color ball) (struct-ref (struct-vtable ball) vtable-offset-user))
(define (owner ball) (struct-ref ball 0))

(define red (make-ball-type 'red))
(define green (make-ball-type 'green))

(define (make-ball type owner) (make-struct type 0 owner))

(define ball (make-ball green 'Nisse))
ball @result{} #<a green ball owned by Nisse>
@end example
[../../../guile-core/libguile/struct.c:465]
guile>

Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]