GNU bug report logs - #41981
Reference Manual on Vtables: Missing Information on Permission "h"

Previous Next

To reply to this bug, email your comments to 41981 AT debbugs.gnu.org.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Sebastian Miele <sebastian.miele <at> gmail.com>
To: bug-guile <at> gnu.org
Subject: Reference Manual on Vtables: Missing Information on Permission "h"
Date: Sun, 21 Jun 2020 15:51:42 +0200

I am on the current master branch. The standard-vtable-fields is
"pwuhuhpwphuhuhuh" on my system and something similar in the Reference
Manual. In particular, it contains the permission letter "h", but I find
no explanation in the manual what that means.

Section 6.6.18.1 (Vtables) just mentions: "It used to be that the second
letter for each field was a permission code, such as ‘w’ for writable or
‘r’ for read-only." And that read-only has become depriciated.

At the end of section 6.6.18.4 (Meta-Vtables) is an example:

  (define* (make-vtable fields #:optional printer)
    (make-struct/no-tail <standard-vtable>
      (make-struct-layout fields)
      printer))

Without information on "h", I was not able to make sense of the fact,
that fields with permission "h" somehow seem to be skipped by
make-struct/no-tail when processing the two init values. In particular,
for some reason, the value of printer is put into field 3 of the new
structure and not in field 1, almost certainly somehow because fields 1
and 2 have "h".

"h" should be documented.

Message #8 received at 41981 <at> debbugs.gnu.org (full text, mbox):

From: dsmich <at> roadrunner.com
To: "'sebastian.miele <at> gmail.com'" <sebastian.miele <at> gmail.com>
Cc: "'41981 <at> debbugs.gnu.org'" <41981 <at> debbugs.gnu.org>
Subject: RE: bug#41981: Reference Manual on Vtables: Missing Information on
 Permission "h"
Date: Sun, 21 Jun 2020 16:29:20 +0000

[Message part 1 (text/plain, inline)]

Is is documented in the docstring:

scheme@(guile-user)> ,d make-struct-layout
- Scheme Procedure: make-struct-layout fields
 Return a new structure layout object.

 FIELDS must be a 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. Allowed
 protections are 'w' for normal fields or 'h' for hidden fields.

 Hidden fields are writable, but they will not consume an
 initializer arg passed to `make-struct'. They are useful to add
 slots to a struct in a way that preserves backward-compatibility
 with existing calls to `make-struct', especially for derived
 vtables.

[Message part 2 (text/html, inline)]

Message #11 received at 41981 <at> debbugs.gnu.org (full text, mbox):

From: Sebastian Miele <sebastian.miele <at> gmail.com>
To: dsmich <at> roadrunner.com
Cc: "'41981 <at> debbugs.gnu.org'" <41981 <at> debbugs.gnu.org>
Subject: Re: bug#41981: Reference Manual on Vtables: Missing Information on
 Permission "h"
Date: Mon, 22 Jun 2020 15:42:46 +0200

dsmich <at> roadrunner.com writes:
> Is is documented in the docstring:
>
> scheme@(guile-user)> ,d make-struct-layout

In the reference manual, a description of make-struct-layout directly
precedes the '(define* (make-vtable ..) ..)' example that cannot be
understood without somehow grasping what is documented about "h" in the
docstring of make-struct-layout. However, the description of
make-struct-layout in the reference manual says: "FIELDS is as described
under ‘make-vtable’ (*note Vtables::)". But that description lacks the
information on "h".

It may be a matter of opinion. But my opinion stronly is that
descriptions about the behavior around permission "h" do should appear
in the reference manual in two places: The description of make-vtable
and the description of make-struct/no-tail.

After glancing at libguile/struct.c, "w", "h", and the depreciated "r"
seem in fact to be all possible permissions. I will prepare a patch after
I finish getting a good overview of Guile.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.