bug#41981: Reference Manual on Vtables: Missing Information on Permission "h"

bug#41981: Reference Manual on Vtables: Missing Information on Permission "h"

[Sebastian Miele]

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.

bug#41981: Reference Manual on Vtables: Missing Information on Permission "h"

[dsmich]

[-- Attachment #1: Type: text/plain, Size: 770 bytes --]

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.



[-- Attachment #2: Type: text/html, Size: 1184 bytes --]

bug#41981: Reference Manual on Vtables: Missing Information on Permission "h"

[Sebastian Miele]

dsmich@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.