From be4f8584983e63905aa409efad11fb7d8d418ccb Mon Sep 17 00:00:00 2001
From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Tue, 21 Sep 2021 20:30:57 +0200
Subject: [PATCH] Add new function `ensure-list'

* doc/lispref/lists.texi (Building Lists): Document it.

* lisp/subr.el (ensure-list): New function.

* lisp/emacs-lisp/shortdoc.el (list): Mention it.
---
 doc/lispref/lists.texi      | 14 ++++++++++++++
 etc/NEWS                    |  5 +++++
 lisp/emacs-lisp/shortdoc.el |  3 +++
 lisp/subr.el                |  8 ++++++++
 test/lisp/subr-tests.el     |  5 +++++
 5 files changed, 35 insertions(+)

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index bbe1dce42d8..6bb11460efe 100644
--- a/doc/lispref/lists.texi
+++ b/doc/lispref/lists.texi
@@ -679,6 +679,20 @@ list are in the same order as in @var{tree}.
     @result{}(1 2 3 4 5 6 7)
 @end example
 
+@defun ensure-list object
+Ensure that we have a list.  If @var{object} is already a list, it is
+returned.  If @var{object} isn't a list, a one-element list containing
+@var{object} is returned.
+
+This is usually useful if you have a variable that may or may not be a
+list, and you can then say, for instance:
+
+@lisp
+(dolist (elem (ensure-list foo))
+  (princ elem))
+@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
diff --git a/etc/NEWS b/etc/NEWS
index d5b6919d6df..eeb753a9af8 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -3825,6 +3825,11 @@ This function works along the line of 'replace-regexp-in-string', but
 it matches on fixed strings instead of regexps, and does not change
 the global match state.
 
++++
+** New function 'ensure-list'.
+This function makes a list of its object if it's not a list already.
+If it's already a list, the list is returned as is.
+
 +++
 ** New function 'split-string-shell-command'.
 This splits a shell command string into separate components,
diff --git a/lisp/emacs-lisp/shortdoc.el b/lisp/emacs-lisp/shortdoc.el
index 3e0d5aef022..d4838ff0f85 100644
--- a/lisp/emacs-lisp/shortdoc.el
+++ b/lisp/emacs-lisp/shortdoc.el
@@ -495,6 +495,9 @@ There can be any number of :example/:result elements."
    :eval (list 1 2 3))
   (number-sequence
    :eval (number-sequence 5 8))
+  (ensure-list
+   :eval (ensure-list "foo")
+   :eval (ensure-list '(1 2 3)))
   "Operations on Lists"
   (append
    :eval (append '("foo" "bar") '("zot")))
diff --git a/lisp/subr.el b/lisp/subr.el
index 6bd9a018eb0..232e684cd46 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -6426,4 +6426,12 @@ This is intended for internal use only."
          (:success t)
          (json-unavailable nil))))
 
+(defun ensure-list (object)
+  "Ensure that we have a list.
+If OBJECT is already a list, OBJECT is returned.  If it's
+not a list, a one-element list containing OBJECT is returned."
+  (if (listp object)
+      object
+    (list object)))
+
 ;;; subr.el ends here
diff --git a/test/lisp/subr-tests.el b/test/lisp/subr-tests.el
index 54bee7bc757..0c3661a296f 100644
--- a/test/lisp/subr-tests.el
+++ b/test/lisp/subr-tests.el
@@ -767,5 +767,10 @@ See https://debbugs.gnu.org/cgi/bugreport.cgi?bug=19350."
       (should-not (equal dir default-directory))
       (should (file-exists-p default-directory)))))
 
+(ert-deftest test-ensure-list ()
+  (should (equal (ensure-list nil) nil))
+  (should (equal (ensure-list :foo) '(:foo)))
+  (should (equal (ensure-list '(1 2 3)) '(1 2 3))))
+
 (provide 'subr-tests)
 ;;; subr-tests.el ends here
-- 
2.39.5