Add new function 'ensure-proper-list' (bug#80598)

* doc/lispref/lists.texi (Building Lists): Document it.
* etc/NEWS: Mention it.
* lisp/emacs-lisp/shortdoc.el (list): Demonstrate it.
* lisp/subr.el (ensure-proper-list): Add it.

doc/lispref/lists.texi

@@ -830,6 +830,26 @@ list, and you can then say, for instance:
 @end lisp
 @end defun
 
+@defun ensure-proper-list object
+This function returns @var{object} as a proper list (@pxref{(elisp) Cons
+Cells}).  If @var{object} is already a proper list, the function returns
+it; otherwise, the function returns a one-element list containing
+@var{object}.
+
+Note that while @code{ensure-list} runs in constant time,
+@code{ensure-proper-list} needs linear time to check if a list is
+proper.  Use this if it is important to not confuse a cons-cell for a
+list:
+
+@lisp
+(ensure-list '(1 . 2))
+    @result{}(1 . 2)
+
+(ensure-proper-list '(1 . 2))
+    @result{}((1 . 2))
+@end lisp
+@end defun
+
 @defun number-sequence from &optional to separation
 This function returns a list of numbers starting with @var{from} and
 incrementing by @var{separation}, and ending at or just before

etc/NEWS

@@ -4426,6 +4426,12 @@ safe to run the command multiple times on subsequent partitions of the
 list of arguments.  The variable 'command-line-max-length' controls the
 partitioning.
 
+** New function 'ensure-proper-list'.
+This function is a variation on 'ensure-list' that checks if an object
+is a proper list, in which case the list will be returned as is,
+otherwise the function will return the object wrapped in a
+singleton list.
+
 
 * Changes in Emacs 31.1 on Non-Free Operating Systems
 

lisp/emacs-lisp/shortdoc.el

@@ -731,7 +731,12 @@ A FUNC form can have any number of `:no-eval' (or `:no-value'),
    :eval (number-sequence 5 8))
   (ensure-list
    :eval (ensure-list "foo")
-   :eval (ensure-list '(1 2 3)))
+   :eval (ensure-list '(1 2 3))
+   :eval (ensure-list '(1 . 2)))
+  (ensure-proper-list
+   :eval (ensure-list "foo")
+   :eval (ensure-list '(1 2 3))
+   :eval (ensure-list '(1 . 2)))
   "Operations on Lists"
   (append
    :eval (append '("foo" "bar") '("zot")))

lisp/subr.el

@@ -7795,6 +7795,15 @@ not a list, return a one-element list containing OBJECT."
       object
     (list object)))
 
+(defun ensure-proper-list (object)
+  "Return OBJECT as a list.
+If OBJECT is already a proper list, return OBJECT itself.  If it's not a
+proper list, return a one-element list containing OBJECT."
+  (declare (side-effect-free error-free))
+  (if (proper-list-p object)
+      object
+    (list object)))
+
 (defmacro with-delayed-message (args &rest body)
   "Like `progn', but display MESSAGE if BODY takes longer than TIMEOUT seconds.
 The MESSAGE form will be evaluated immediately, but the resulting