From b99a34bcb030d59e0e272b3379d1725a6eb01d95 Mon Sep 17 00:00:00 2001 From: Eli Zaretskii Date: Tue, 1 Dec 2015 18:16:22 +0200 Subject: [PATCH] Document 'directory-files-recursively' * lisp/files.el (directory-files-recursively): Doc fix. Rename the argument MATCH to REGEXP, to be more explicit about its form. * doc/lispref/files.texi (Contents of Directories): Improve the documentation of 'directory-files-recursively'. Add cross-references. * etc/NEWS: Move the entry for 'directory-files-recursively' to its place and mark it documented. --- doc/lispref/files.texi | 20 ++++++++++++++------ etc/NEWS | 7 ++++--- lisp/files.el | 16 +++++++++------- 3 files changed, 27 insertions(+), 16 deletions(-) diff --git a/doc/lispref/files.texi b/doc/lispref/files.texi index 9a1b2cd217f..e8ed7ccd9f7 100644 --- a/doc/lispref/files.texi +++ b/doc/lispref/files.texi @@ -2632,12 +2632,20 @@ An error is signaled if @var{directory} is not the name of a directory that can be read. @end defun -@defun directory-files-recursively directory match &optional include-directories -Return all files under @var{directory} whose file names match -@var{match} recursively. The file names are returned depth first, -meaning that contents of sub-directories are returned before contents -of the directories. If @var{include-directories} is non-@code{nil}, -also return directory names that have matching names. +@defun directory-files-recursively directory regexp &optional include-directories +Return all files under @var{directory} whose names match @var{regexp}. +This function searches the specified @var{directory} and its +sub-directories, recursively, for files whose basenames (i.e., without +the leading directories) match the specified @var{regexp}, and returns +a list of the absolute file names of the matching files +(@pxref{Relative File Names, absolute file names}). The file names +are returned in depth-first order, meaning that files in some +sub-directory are returned before the files in its parent directory. +In addition, matching files found in each subdirectory are sorted +alphabetically by their basenames. By default, directories whose +names match @var{regexp} are omitted from the list, but if the +optional argument @var{include-directories} is non-@code{nil}, they +are included. @end defun @defun directory-files-and-attributes directory &optional full-name match-regexp nosort id-format diff --git a/etc/NEWS b/etc/NEWS index b9e0bd4ba24..bd7435b1760 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -181,9 +181,6 @@ for use in Emacs bug reports. hiding character but the default `.' can be used by let-binding the variable `read-hide-char'. -** A new function `directory-files-recursively' returns all matching -files (recursively) under a directory. - ** The new function `directory-name-p' can be used to check whether a file name (as returned from, for instance, `file-name-all-completions' is a directory file name. It returns non-nil if the last character in @@ -1137,6 +1134,10 @@ of subprocess. process filter, sentinel, etc., through keyword arguments (similar to `make-network-process'). ++++ +** A new function `directory-files-recursively' returns all matching +files (recursively) under a directory. + +++ ** New variable `inhibit-message', when bound to non-nil, inhibits `message' and related functions from displaying messages the Echo diff --git a/lisp/files.el b/lisp/files.el index e892ac6b94b..f37c23b7bdd 100644 --- a/lisp/files.el +++ b/lisp/files.el @@ -744,11 +744,13 @@ The path separator is colon in GNU and GNU-like systems." (and (> (length name) 0) (char-equal (aref name (1- (length name))) ?/))) -(defun directory-files-recursively (dir match &optional include-directories) - "Return all files under DIR that have file names matching MATCH (a regexp). +(defun directory-files-recursively (dir regexp &optional include-directories) + "Return list of all files under DIR that have file names matching REGEXP. This function works recursively. Files are returned in \"depth first\" -and alphabetical order. -If INCLUDE-DIRECTORIES, also include directories that have matching names." +order, and files from each directory are sorted in alphabetical order. +Each file name appears in the returned list in its absolute form. +Optional argument INCLUDE-DIRECTORIES non-nil means also include in the +output directories whose names match REGEXP." (let ((result nil) (files nil) ;; When DIR is "/", remote file names like "/method:" could @@ -764,11 +766,11 @@ If INCLUDE-DIRECTORIES, also include directories that have matching names." (unless (file-symlink-p full-file) (setq result (nconc result (directory-files-recursively - full-file match include-directories)))) + full-file regexp include-directories)))) (when (and include-directories - (string-match match leaf)) + (string-match regexp leaf)) (setq result (nconc result (list full-file))))) - (when (string-match match file) + (when (string-match regexp file) (push (expand-file-name file dir) files))))) (nconc result (nreverse files))))