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.

diff --git a/doc/lispref/lists.texi b/doc/lispref/lists.texi
index bbe1dce42d84d24c7e33d8fdc9eec941dec623e4..6bb11460efe22620f71e364c32c789cda1292d34 100644 (file)
--- 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 d5b6919d6dfb546bb57325423bfb12a057ff8d30..eeb753a9af88ada56697aae2a4cd656a7575376b 100644 (file)
--- 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 3e0d5aef0220ef2e51e90410db82b2e7336cc2fb..d4838ff0f859ae1674adb6f919e177a548d45073 100644 (file)
--- 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 6bd9a018eb03f4617f933601a685986d51322a78..232e684cd4650c78e39ec218da3d8f83031353fc 100644 (file)
--- 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 54bee7bc75714082879a8ec00263be2f1a653fbf..0c3661a296fdd5ac3597065fefcb350aeac798f6 100644 (file)
--- 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