summaryrefslogtreecommitdiff
path: root/libguile/struct.c
diff options
context:
space:
mode:
authorGreg J. Badros <gjb@cs.washington.edu>1999-12-13 03:40:23 +0000
committerGreg J. Badros <gjb@cs.washington.edu>1999-12-13 03:40:23 +0000
commit4079f87ed21341a8654ecaa29ac3e6a2344d9252 (patch)
treed9381ae0256c3daae81acde78bf40d1d12cd12e5 /libguile/struct.c
parent75948d1b314685312f8d62315c4bec6bd003fca4 (diff)
downloadguile-4079f87ed21341a8654ecaa29ac3e6a2344d9252.tar.gz
* Makefile.am: Fix ETAGS_ARGS to recognize GUILE_PROC,
GUILE_PROC1. Build guile-procedures.txt, and add that file to pkgdata_DATA. * load.c: Added `pkgdata-dir', `site-dir', `library-dir' primitives. * guile-doc-snarf.awk: Drop trailing space when no arguments: e.g., "(foo )" is now "(foo)". * *.c: moved all the documentation for primitives from guile-doc/ref/{appendices,posix,scheme}.texi into the source code. This leaves about half of the primitives undocumented. Also, all the markup is currently still texinfo. I don't have a problem with texinfo per se, but the markup is not very descriptive or accurate.
Diffstat (limited to 'libguile/struct.c')
-rw-r--r--libguile/struct.c105
1 files changed, 98 insertions, 7 deletions
diff --git a/libguile/struct.c b/libguile/struct.c
index f6670486b..f3c50509a 100644
--- a/libguile/struct.c
+++ b/libguile/struct.c
@@ -68,7 +68,16 @@ SCM scm_struct_table;
GUILE_PROC (scm_make_struct_layout, "make-struct-layout", 1, 0, 0,
(SCM fields),
-"")
+"Return a new structure layout object.
+
+@var{fields} must be a read-only string made up of pairs of characters
+strung together. The first character of each pair describes a field
+type, the second a field protection. Allowed types are 'p' for
+GC-protected Scheme data, 'u' for unprotected binary data, and 's' for
+fields that should point to the structure itself. Allowed protections
+are 'w' for mutable fields, 'r' for read-only fields, and 'o' for opaque
+fields. The last field protection specification may be capitalized to
+indicate that the field is a tail-array.")
#define FUNC_NAME s_scm_make_struct_layout
{
SCM new_sym;
@@ -233,7 +242,7 @@ scm_struct_init (SCM handle, int tail_elts, SCM inits)
GUILE_PROC (scm_struct_p, "struct?", 1, 0, 0,
(SCM x),
-"")
+"Return #t iff @var{obj} is a structure object, else #f.")
#define FUNC_NAME s_scm_struct_p
{
return SCM_BOOL(SCM_NIMP (x) && SCM_STRUCTP (x));
@@ -242,7 +251,7 @@ GUILE_PROC (scm_struct_p, "struct?", 1, 0, 0,
GUILE_PROC (scm_struct_vtable_p, "struct-vtable?", 1, 0, 0,
(SCM x),
-"")
+"Return #t iff obj is a vtable structure.")
#define FUNC_NAME s_scm_struct_vtable_p
{
SCM layout;
@@ -360,7 +369,19 @@ scm_struct_free_entity (SCM *vtable, SCM *data)
GUILE_PROC (scm_make_struct, "make-struct", 2, 0, 1,
(SCM vtable, SCM tail_array_size, SCM 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{inits} are optional arguments describing how successive fields
+of the structure should be initialized. Only fields with protection 'r'
+or 'w' can be initialized -- fields of protection 's' are automatically
+initialized to point to the new structure itself; fields of protection 'o'
+can not be initialized by Scheme programs.")
#define FUNC_NAME s_scm_make_struct
{
SCM layout;
@@ -401,7 +422,71 @@ GUILE_PROC (scm_make_struct, "make-struct", 2, 0, 1,
GUILE_PROC (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1,
(SCM extra_fields, SCM tail_array_size, SCM init),
-"")
+"Return a new, self-describing vtable structure.
+
+@var{new-fields} is a layout specification describing fields
+of the resulting structure beginning at the position bound to
+@code{vtable-offset-user}.
+
+@var{tail-size} specifies the size of the tail-array (if any) of
+this vtable.
+
+@var{inits} initializes the fields of the vtable. Minimally, one
+initializer must be provided: the layout specification for instances
+of the type this vtable will describe. If a second initializer is
+provided, it will be interpreted as a print call-back function.
+
+@example
+;;; loading ,a...
+(define x
+ (make-vtable-vtable (make-struct-layout (quote pw))
+ 0
+ 'foo))
+
+(struct? x)
+@result{} #t
+(struct-vtable? x)
+@result{} #t
+(eq? x (struct-vtable x))
+@result{} #t
+(struct-ref x vtable-offset-user)
+@result{} foo
+(struct-ref x 0)
+@result{} pruosrpwpw
+
+
+(define y
+ (make-struct x
+ 0
+ (make-struct-layout (quote pwpwpw))
+ 'bar))
+
+(struct? y)
+@result{} #t
+(struct-vtable? y)
+@result{} #t
+(eq? x y)
+@result{} ()
+(eq? x (struct-vtable y))
+@result{} #t
+(struct-ref y 0)
+@result{} pwpwpw
+(struct-ref y vtable-offset-user)
+@result{} bar
+
+
+(define z (make-struct y 0 'a 'b 'c))
+
+(struct? z)
+@result{} #t
+(struct-vtable? z)
+@result{} ()
+(eq? y (struct-vtable z))
+@result{} #t
+(map (lambda (n) (struct-ref z n)) '(0 1 2))
+@result{} (a b c)
+@end example
+")
#define FUNC_NAME s_scm_make_vtable_vtable
{
SCM fields;
@@ -439,7 +524,13 @@ GUILE_PROC (scm_make_vtable_vtable, "make-vtable-vtable", 2, 0, 1,
GUILE_PROC (scm_struct_ref, "struct-ref", 2, 0, 0,
(SCM handle, SCM pos),
-"")
+"@deffnx primitive struct-set! struct n value
+Access (or modify) the @var{n}th field of @var{struct}.
+
+If the field is of type 'p', then it can be set to an arbitrary value.
+
+If the field is of type 'u', then it can only be set to a non-negative
+integer value small enough to fit in one machine word.")
#define FUNC_NAME s_scm_struct_ref
{
SCM answer = SCM_UNDEFINED;
@@ -592,7 +683,7 @@ GUILE_PROC (scm_struct_set_x, "struct-set!", 3, 0, 0,
GUILE_PROC (scm_struct_vtable, "struct-vtable", 1, 0, 0,
(SCM handle),
-"")
+"Return the vtable structure that describes the type of @var{struct}.")
#define FUNC_NAME s_scm_struct_vtable
{
SCM_VALIDATE_STRUCT(1,handle);