Function: file-expand-wildcards

file-expand-wildcards is a byte-compiled function defined in files.el.gz.

Signature

(file-expand-wildcards PATTERN &optional FULL REGEXP)

Documentation

Expand (a.k.a. "glob") file-name wildcard pattern PATTERN.

This returns a list of file names that match PATTERN. The returned list of file names is sorted in the string< order.

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 returned list of file names is sorted in the string< order.

If PATTERN is written as an absolute file name, the expansions in the returned list are also absolute.

If PATTERN is written as a relative file name, it is interpreted relative to the current default-directory. The file names returned are normally also relative to the current default directory. However, if FULL is non-nil, they are absolute.

Other relevant functions are documented in the file group.

View in manual

Probably introduced at or before Emacs version 20.4.

Shortdoc

;; file
(file-expand-wildcards "/tmp/*.png")
    e.g. => ("/tmp/foo.png" "/tmp/zot.png")
  (file-expand-wildcards "/*/foo.png")
    e.g. => ("/tmp/foo.png" "/var/foo.png")

Source Code

;; Defined in /usr/src/emacs/lisp/files.el.gz
(defun file-expand-wildcards (pattern &optional full regexp)
  "Expand (a.k.a. \"glob\") file-name wildcard pattern PATTERN.
This returns a list of file names that match PATTERN.
The returned list of file names is sorted in the `string<' order.

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 returned list of file names is sorted in the `string<' order.

If PATTERN is written as an absolute file name, the expansions in
the returned list are also absolute.

If PATTERN is written as a relative file name, it is interpreted
relative to the current `default-directory'.
The file names returned are normally also relative to the current
default directory.  However, if FULL is non-nil, they are absolute."
  (save-match-data
    (let* ((nondir (file-name-nondirectory pattern))
	   (dirpart (file-name-directory pattern))
	   ;; A list of all dirs that DIRPART specifies.
	   ;; This can be more than one dir
	   ;; if DIRPART contains wildcards.
	   (dirs (if (and dirpart
			  (string-match "[[*?]" (file-local-name dirpart)))
		     (mapcar #'file-name-as-directory
			     (file-expand-wildcards
                              (directory-file-name dirpart) nil regexp))
		   (list dirpart)))
	   contents)
      (dolist (dir (nreverse dirs))
	(when (or (null dir)	; Possible if DIRPART is not wild.
		  (file-accessible-directory-p dir))
          (if (equal "" nondir)
              ;; `nondir' is "" when the pattern ends in "/".  Basically ""
              ;; refers to the directory itself, like ".", but it's not
              ;; among the names returned by `directory-files', so we have
              ;; to special-case it.
              (push (or dir nondir) contents)
	    (let ((this-dir-contents
		   ;; Filter out "." and ".."
		   (delq nil
                         (mapcar (lambda (name)
                                   (unless (string-match "\\`\\.\\.?\\'"
                                                         (file-name-nondirectory
                                                          name))
                                     name))
                                 (directory-files
                                  (or dir ".") full
                                  (if regexp
                                      ;; We're matching each file name
                                      ;; element separately.
                                      (concat "\\`" nondir "\\'")
				   (wildcard-to-regexp nondir)))))))
	      (setq contents
		    (nconc
		     (if (and dir (not full))
			 (mapcar (lambda (name) (concat dir name))
                                 this-dir-contents)
		       this-dir-contents)
		     contents))))))
      contents)))