Extend file-expand-wildcards to allow regexps

* doc/lispref/files.texi (Contents of Directories): Document it.
* lisp/files.el (file-expand-wildcards): Extend to allow regexps.

* lisp/emacs-lisp/shortdoc.el (file): Expand the
file-expand-wildcards example.

doc/lispref/files.texi

@@ -3112,10 +3112,16 @@ except those two.  It is useful as the @var{match-regexp} argument to
 returns @code{nil}, if directory @samp{/foo} is empty.
 @end defvr
 
-@defun file-expand-wildcards pattern &optional full
+@defun file-expand-wildcards pattern &optional full regexp
 This function expands the wildcard pattern @var{pattern}, returning
 a list of file names that match it.
 
+@var{pattern} is, by default, a ``glob''/wildcard string, e.g.,
+@samp{"/tmp/*.png"} or @samp{"/*/*/foo.png"}, but can also be a
+regular expression if the optional @var{regexp} parameter is non-nil.
+In any case, the matches are applied per sub-directory, so a match
+can't span a parent/sub directory.
+
 If @var{pattern} is written as an absolute file name,
 the values are absolute also.
 

etc/NEWS

@@ -1936,6 +1936,9 @@ Previously it produced a nonsense value, -1, that was never intended.
 
 * Lisp Changes in Emacs 29.1
 
++++
+** 'file-expand-wildcards' can now also take a regexp match.
+
 ---
 ** vc-mtn (the backend for Monotone) has been made obsolete.
 

lisp/emacs-lisp/shortdoc.el

@@ -468,7 +468,9 @@ A FUNC form can have any number of `:no-eval' (or `:no-value'),
    :no-eval* (directory-files-and-attributes "/tmp/foo"))
   (file-expand-wildcards
    :no-eval (file-expand-wildcards "/tmp/*.png")
-   :eg-result ("/tmp/foo.png" "/tmp/zot.png"))
+   :eg-result ("/tmp/foo.png" "/tmp/zot.png")
+   :no-eval (file-expand-wildcards "/*/foo.png")
+   :eg-result ("/tmp/foo.png" "/var/foo.png"))
   (locate-dominating-file
    :no-eval (locate-dominating-file "foo.png" "/tmp/foo/bar/zot")
    :eg-result "/tmp/foo.png")

lisp/files.el

@@ -7198,13 +7198,21 @@ by `sh' are supported."
   :type 'string
   :group 'dired)
 
-(defun file-expand-wildcards (pattern &optional full)
+(defun file-expand-wildcards (pattern &optional full regexp)
   "Expand wildcard pattern PATTERN.
 This returns a list of file names that match the pattern.
-Files are sorted in `string<' order.
 
-If PATTERN is written as an absolute file name,
-the values are absolute also.
+PATTERN is, by default, a \"glob\"/wildcard string, e.g.,
+\"/tmp/*.png\" or \"/*/*/foo.png\", but can also be a regular
+expression if the optional REGEXP parameter is non-nil.  In any
+case, the matches are applied per sub-directory, so a match can't
+span a parent/sub directory, which means that a regexp bit can't
+contain the \"/\" character.
+
+The list of files returned are sorted in `string<' order.
+
+If PATTERN is written as an absolute file name, the values are
+absolute also.
 
 If PATTERN is written as a relative file name, it is interpreted
 relative to the current default directory, `default-directory'.
@@ -7219,7 +7227,8 @@ default directory.  However, if FULL is non-nil, they are absolute."
 	   (dirs (if (and dirpart
 			  (string-match "[[*?]" (file-local-name dirpart)))
 		     (mapcar 'file-name-as-directory
-			     (file-expand-wildcards (directory-file-name dirpart)))
+			     (file-expand-wildcards
+                              (directory-file-name dirpart) nil regexp))
 		   (list dirpart)))
 	   contents)
       (dolist (dir dirs)
@@ -7233,7 +7242,9 @@ default directory.  However, if FULL is non-nil, they are absolute."
                                                        (file-name-nondirectory name))
                                    name))
 			       (directory-files (or dir ".") full
-						(wildcard-to-regexp nondir))))))
+                                                (if regexp
+                                                    nondir
+						  (wildcard-to-regexp nondir)))))))
 	    (setq contents
 		  (nconc
 		   (if (and dir (not full))