Deprecate opaque struct fields

* NEWS: Add entry.
* doc/ref/api-data.texi (Vtables, Structure Basics): Remove mention of
  opaque field protection.
* libguile/struct.c (scm_make_struct_layout, scm_make_struct_no_tail):
  Remove discussion of opaque fields.
  (set_vtable_layout_flags): Issue a deprecation warning when opaque
  fields are used.

3 files changed, 27 insertions, 15 deletions

diff --git a/NEWS b/NEWS
index 78e3b30c3..fec9af30f 100644
--- a/NEWS
+++ b/NEWS
@@ -67,6 +67,20 @@ structure.  However this was a little used complication without any use
 in Scheme code.  To replace it, just use "p" slots and initialize the
 slot values manually on initialization.
 
+** Struct fields with opaque ("o") protection deprecated
+
+Struct fields are declared with a "protection", meaning read-only ('r'),
+read-write ('w'), or opaque ('o').  There is also "hidden" ('o') which
+is read-write but which isn't initialized by arguments passed to
+`make-struct/no-tail', but that's a detail.  Opaque struct fields were
+used to allocate storage in a struct that could only be accessed by C.
+This facility was very rarely used (unused in Guile itself) but now that
+we are implementing more and more in Scheme, it is completely useless.
+
+To enforce permissions on struct fields, instead layer on an abstraction
+at a higher level, in the same way that immutable record fields are
+simply those which don't have an accessor.
+
 * Bug fixes
 
 ** Enable GNU Readline 7.0's support for "bracketed paste".
diff --git a/doc/ref/api-data.texi b/doc/ref/api-data.texi
index faddc3f65..e0f8be324 100644
--- a/doc/ref/api-data.texi
+++ b/doc/ref/api-data.texi
@@ -8795,9 +8795,6 @@ The second letter for each field is a permission code,
 @item
 @code{r} -- read-only, the field can be read but not written.
 @item
-@code{o} -- opaque, the field can be neither read nor written at the
-Scheme level.  This can be used for fields which should only be used
-from C code.
 @end itemize
 
 Here are some examples.
@@ -8850,11 +8847,6 @@ used to have a @code{make-struct} that took an additional argument;
 while we deprecate that old interface, @code{make-struct/no-tail} is the
 new name for this functionality.
 
-Fields with permission @code{o} opaque fields are ignored for the
-@var{init} arguments, ie.@: an argument is not consumed by such a field.
-An @code{o} slot is always set to @code{#f} or 0 (with the intention
-that C code will do something to it later).
-
 For example,
 
 @example
@@ -8886,8 +8878,7 @@ Return @code{#t} if @var{obj} is a structure, or @code{#f} if not.
 Return the contents of field number @var{n} in @var{struct}.  The
 first field is number 0.
 
-An error is thrown if @var{n} is out of range, or if the field cannot
-be read because it's @code{o} opaque.
+An error is thrown if @var{n} is out of range.
 @end deffn
 
 @deffn {Scheme Procedure} struct-set! struct n value
@@ -8896,7 +8887,7 @@ Set field number @var{n} in @var{struct} to @var{value}.  The first
 field is number 0.
 
 An error is thrown if @var{n} is out of range, or if the field cannot
-be written because it's @code{r} read-only or @code{o} opaque.  
+be written because it's @code{r} read-only.
 @end deffn
 
 @deffn {Scheme Procedure} struct-vtable struct
diff --git a/libguile/struct.c b/libguile/struct.c
index 5c03f4fb0..1363fea90 100644
--- a/libguile/struct.c
+++ b/libguile/struct.c
@@ -71,8 +71,8 @@ SCM_DEFINE (scm_make_struct_layout, "make-struct-layout", 1, 0, 0,
 	    "type, the second a field protection.  Allowed types are 'p' for\n"
 	    "GC-protected Scheme data, 'u' for unprotected binary data.  \n"
             "Allowed protections\n"
-	    "are 'w' for mutable fields, 'h' for hidden fields, 'r' for read-only\n"
-            "fields, and 'o' for opaque fields.\n\n"
+	    "are 'w' for mutable fields, 'h' for hidden fields, and\n"
+            "'r' for read-only fields.\n\n"
             "Hidden fields are writable, but they will not consume an initializer arg\n"
             "passed to @code{make-struct}. They are useful to add slots to a struct\n"
             "in a way that preserves backward-compatibility with existing calls to\n"
@@ -174,6 +174,13 @@ set_vtable_layout_flags (SCM vtable)
 	    flags &= ~SCM_VTABLE_FLAG_SIMPLE_RW;
 	    break;
 
+          case 'o':
+          case 'O':
+            scm_c_issue_deprecation_warning
+              ("Opaque struct fields are deprecated.  Struct field protection "
+               "should be layered on at a higher level.");
+            /* Fall through.  */
+
 	  default:
 	    flags = 0;
 	  }
@@ -564,8 +571,8 @@ SCM_DEFINE (scm_make_struct_no_tail, "make-struct/no-tail", 1, 0, 1,
 	    "The @var{init1}, @dots{} are optional arguments describing how\n"
 	    "successive fields of the structure should be initialized.\n"
             "Only fields with protection 'r' or 'w' can be initialized.\n"
-            "Fields with protection 'o' can not be initialized by Scheme\n"
-            "programs.\n\n"
+            "Hidden fields (those with protection 'h') have to be manually\n"
+            "set.\n\n"
 	    "If fewer optional arguments than initializable fields are supplied,\n"
 	    "fields of type 'p' get default value #f while fields of type 'u' are\n"
 	    "initialized to 0.")