Subject: bug#77058: [PATCH] Add cl-with-accessors

From: Eli Zaretskii <[email-masked]>
Date: Mon, 17 Mar 2025 14:09:04 +0200

> Date: Sun, 16 Mar 2025 18:23:25 +0000
> From:  Okamsn via "Bug reports for GNU Emacs,
>  the Swiss army knife of text editors" <[email-masked]>
> 
> The attached patch adds the macro `cl-with-accessors'.  This macro uses 
> `cl-symbol-macrolet' to treat a symbol like a use of an accessor 
> function, such as those made by `cl-defstruct' and `cl-defclass'. This 
> can be helpful when using repeated calls to read and write with the 
> functions.
> 
> It is based on the description at
> https://www.lispworks.com/documentation/HyperSpec/Body/m_w_acce.htm
> 
> Also, in the test `cl-lib-struct-accessors' in 
> test/lisp/emacs-lisp/cl-lib-tests.el, it checks for the keyword 
> `:readonly', but the documented keyword is `:read-only'.  Is this a 
> typo, or was this intentional?

Thanks, I added Stefan to the discussion in the hope that he might
have comments.

A few comments about the documentation parts of the patch below.

> --- a/doc/misc/cl.texi
> +++ b/doc/misc/cl.texi
> @@ -4225,6 +4225,19 @@ Structures
>  
>  Other slot options are currently ignored.
>  
> +The macro @code{cl-with-accessors} can simplify code that repeatedly
> +accesses slots.

This macro should be documented using @defmac, and the description
should be more detailed, at least as detailed as the doc string.
Since you say the macro simplifies some typical usage patterns, it
would be good to show how it does so, perhaps by showing an example of
code without the macro, and then the same code using the macro.

> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -2496,6 +2496,13 @@ This function is like 'type-of' except that it sometimes returns
>  a more precise type.  For example, for nil and t it returns 'null'
>  and 'boolean' respectively, instead of just 'symbol'.
>  
> +** New macro 'cl-with-accessors'

This should end in a period.

Also, since the necessary changes to the manual are included, the NEWS
entry should be marked with "+++" (see the explanation at the top of
NEWS).

> +This macro is similar to 'map-let', but works with structures and their
> +accessors functions.  It is useful when slots' accessor functions are
> +use repeatedly, such as reading from a slot and then writing to that
   ^^^
"used"

> +(defmacro cl-with-accessors (bindings instance &rest body)
> +  "Generate code using symbols as accessing expressions for INSTANCE inside BODY.

It is best to reference all of the mandatory arguments in the first
line.  In this case, BINDINGS is not mentioned, not even in the rest
of the doc string.