doc srfi-17

[Kevin Ryde]

I'm looking at the following to expand and clarify the present couple
of paragraphs on srfi-17.

Notwithstanding the criticisms of `setter' as a procedure with setter
it'd be good if guile implemented the whole of the srfi.  Would that
need a new C function to set that field of the pws smob, or is there
something hiding but unused for that already?




6.4.14 SRFI-17 - Generalized set!
---------------------------------

This SRFI implements a generalized `set!', allowing some "referencing"
functions to be used as the target location of a `set!'.  This feature
is available with

     (use-modules (srfi srfi-17))

For example, `vector-ref' is extended so that

     (set! (vector-ref vec idx) new-value)

is equivalent to

     (vector-set! vec idx new-value)

   The idea is that a `vector-ref' expression identifies a location,
which may be either fetched or stored.  The same form is used for the
location in both cases, encouraging visual clarity.  This is similar to
the idea of an "lvalue" in C.

   The mechanism for this kind of `set!' is in the Guile core (*note
Procedures with Setters::).  This module adds definitions of the
following functions as procedures with setters, allowing them to be
targets of a `set!',

     car, cdr, caar, cadr, cdar, cddr, caaar, caadr, cadar, caddr,
     cdaar, cdadr, cddar, cdddr, caaaar, caaadr, caadar, caaddr,
     cadaar, cadadr, caddar, cadddr, cdaaar, cdaadr, cdadar, cdaddr,
     cddaar, cddadr, cdddar, cddddr

     string-ref, vector-ref

 -- Function: getter-with-setter
     The same as the Guile core `make-procedure-with-setter' (*note
     Procedures with Setters::).

   The SRFI specifies `setter' (*note Procedures with Setters::) as a
procedure with setter, allowing the setter for a procedure to be
changed, eg. `(set! (setter foo) my-new-setter-handler)'.  Currently
Guile does not implement this, a setter can only be specified on
creation (`getter-with-setter' above).