master 393f58c85ae: 'vtable-update-object' can now be called with one argument

[Eli Zaretskii]

branch: master
commit 393f58c85aeb78f814866ccaad9ae7efd3fa6766
Author: Adam Porter <adam@alphapapa.net>
Commit: Eli Zaretskii <eliz@gnu.org>

    'vtable-update-object' can now be called with one argument
    
    It's often necessary to update the representation of a single
    object in a table (e.g a struct, whose identity does not change
    when its slots'
    values are changed).  To do so, now the function may be called
    like this:
    
      (vtable-update-object table object)
    
    Instead of like this:
    
      (vtable-update-object table object object)
    
    This also documents the behavior of the just-discovered limitation filed
    as bug#69837.
    * lisp/emacs-lisp/vtable.el (vtable-update-object): Make 'old-object'
    argument optional.  (Bug#69666)
    
    * doc/misc/vtable.texi (Interface Functions): Update documentation.
    
    * etc/NEWS: Add news entry.
---
 doc/misc/vtable.texi      | 13 ++++++++++---
 etc/NEWS                  |  9 +++++++++
 lisp/emacs-lisp/vtable.el | 15 +++++++++++++--
 3 files changed, 32 insertions(+), 5 deletions(-)

diff --git a/doc/misc/vtable.texi b/doc/misc/vtable.texi
index a4f2ed29d93..dd5b70cf32f 100644
--- a/doc/misc/vtable.texi
+++ b/doc/misc/vtable.texi
@@ -554,12 +554,19 @@ the object after this object; otherwise append to 
@var{table}.  This
 also updates the displayed table.
 @end defun
 
-@defun vtable-update-object table object old-object
-Change @var{old-object} into @var{object} in @var{table}.  This also
-updates the displayed table.
+@defun vtable-update-object table object &optional old-object
+Update @var{object}'s representation in @var{table}.  Optional argument
+@var{old-object}, if non-@code{nil}, means to replace @var{old-object}
+with @var{object} and redisplay the associated row in the table.  In
+either case, if the existing object is not found in the table (being
+compared with @code{equal}), signal an error.
 
 This has the same effect as calling @code{vtable-remove-object} and
 then @code{vtable-insert-object}, but is more efficient.
+
+Note a limitation: if the table's buffer is not in a visible window, or
+if its window has changed width since it was updated, updating the table
+is not possible, and an error is signaled.
 @end defun
 
 @defun vtable-column table index
diff --git a/etc/NEWS b/etc/NEWS
index 69e61d91b0e..ba0e4c80fa0 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -2197,6 +2197,15 @@ aforementioned functions:
     (and (arrayp executing-kbd-macro)
          (>= executing-kbd-macro-index (length executing-kbd-macro))))
 
++++
+** 'vtable-update-object' updates an existing object with just two arguments.
+It is now possible to update the representation of an object in a vtable
+by calling 'vtable-update-object' with just the vtable and the object as
+arguments.  (Previously the 'old-object' argument was required which, in
+this case, would mean repeating the object in the argument list.)  When
+replacing an object with a different one, passing both the new and old
+objects is still necessary.
+
 
 * Changes in Emacs 30.1 on Non-Free Operating Systems
 
diff --git a/lisp/emacs-lisp/vtable.el b/lisp/emacs-lisp/vtable.el
index 5f7d3ae5210..d8e5136c666 100644
--- a/lisp/emacs-lisp/vtable.el
+++ b/lisp/emacs-lisp/vtable.el
@@ -283,8 +283,16 @@ If it can't be found, return nil and don't move point."
       (goto-char (prop-match-beginning match))
     (end-of-line)))
 
-(defun vtable-update-object (table object old-object)
-  "Replace OLD-OBJECT in TABLE with OBJECT."
+(defun vtable-update-object (table object &optional old-object)
+  "Update OBJECT's representation in TABLE.
+If OLD-OBJECT is non-nil, replace OLD-OBJECT with OBJECT and display it.
+In either case, if the existing object is not found in the table (being
+compared with `equal'), signal an error.  Note a limitation: if TABLE's
+buffer is not in a visible window, or if its window has changed width
+since it was updated, updating the TABLE is not possible, and an error
+is signaled."
+  (unless old-object
+    (setq old-object object))
   (let* ((objects (vtable-objects table))
          (inhibit-read-only t))
     ;; First replace the object in the object storage.
@@ -300,6 +308,9 @@ If it can't be found, return nil and don't move point."
         (error "Can't find the old object"))
       (setcar (cdr objects) object))
     ;; Then update the cache...
+    ;; FIXME: If the table's buffer has no visible window, or if its
+    ;; width has changed since the table was updated, the cache key will
+    ;; not match and the object can't be updated.  (Bug #69837).
     (if-let ((line-number (seq-position (car (vtable--cache table)) old-object
                                         (lambda (a b)
                                           (equal (car a) b))))