Hi Ludovic,
l...@gnu.org (Ludovic Courtès) writes:
> Documentation attached. Comments?
Thanks! Looks good to me, modulo a few comments below.
> BTW, why does ‘set-field’ has the record as its 2nd argument instead of
> 1st (unlike ‘set-fields’)?
Good question. I followed the syntax of 'set-field' from your original
patch, but that argument order did not make sense for 'set-fields'.
On one hand, (set-field (person-address address-city) person "Boston")
matches the order of the corresponding english "set the field
(person-address address-city) of person to Boston", and thus reads a bit
more naturally to my ears.
On the other hand, it would be good for the two syntaxes to be
consistent with each other, and (set-field <record> <field> <value>)
would also be more consistent with things like 'hash-set!',
'vector-set!', etc.
Honestly, I could go either way. If you think it makes sense to change
the order to (set-field <record> <field> <value>), I'd be glad to make
that change. Obviously it's now or never :)
> +@unnumberedsubsubsec Functional ``Setters''
> +
> +@cindex functional setters
> +
> +When writing code in a functional style, it is desirable to never alter
> +the contents of records. For such code, a simple way to return new
> +record instances based on existing ones is highly desirable.
> +
> +The @code{(srfi srfi-9 gnu)} module extends SRFI-9 with facilities to
> +return new record instances based on existing ones, only with one or
> +more field values changed---@dfn{functional setters}. First, the
> +@code{define-immutable-record-type} works like
> +@code{define-record-type}, except that setters are defined as functional
> +setters.
"except that the fields are immutable and the setters are ..."
[...]
> +@deffn {Scheme Syntax} set-field (field sub-fields ...) record value
> +Return a new record of @var{record}'s type whose fields are equal to
> +the corresponding fields of @var{record} except for the one specified by
> +@var{field}.
> +
> +@var{field} must be the name of the getter corresponding to the field of
> +@var{record} being ``set''. Subsequent @var{sub-fields} must be record
This is the first time that "getter" is used, but it has not been made
clear that you mean what has been called an "accessor" elsewhere in the
doc. More generally, there is a confusing mixture of the
accessor/modifier and getter/setter terminology. I wonder if it would
made sense to do some kind of find/replace in this section.
Other than that, it looks great, thanks!
Mark
