Elisp: Traverse Directory

By Xah Lee. Date: . Last updated: .

The function directory-files return a list of files in a directory.

(directory-files DIRECTORY &optional FULL MATCH NOSORT) → no recurse into sub-directories. Can filter by regex. See optional params.

If you want to list files of all nested subdirectories, use the package find-lisp.el

(require 'find-lisp)

The package provides the following functions:

(find-lisp-find-files dirpath regex) → recursive, filter by regex.

(find-lisp-find-files-internal dirpath 'file-predicate-p 'dir-predicate-p) → recursive, filter by predicate functions.

They return a list of all files in the directory dirpath.

Here's a simple example:

;; traverse a dir

(require 'find-lisp)

;; insert file path of all html files in the directory, recursive all sub-directory
(mapc

 (lambda (x)
   (insert x)
   (insert "\n"))

 (find-lisp-find-files
  "/home/john/web/"
  "\\.html$"
  ))

Filter by a General Predicate Function

Sometimes you need to use a general function that answer yes or no for a file/directory, not just by regex. For example, if the file size is larger than 1 megabytes, skip.

In that case, you can use the function find-lisp-find-files-internal.

(find-lisp-find-files-internal DIRECTORY FILE-PREDICATE
DIRECTORY-PREDICATE)

Find files under DIRECTORY which satisfy FILE-PREDICATE.
FILE-PREDICATE is a function which takes two arguments: the file and its
directory.

DIRECTORY-PREDICATE is used to decide whether to descend into directories.
It is a function which takes two arguments, the directory and its parent.

Here's example:

;; traverse a dir

(require 'find-lisp)

(find-lisp-find-files-internal
 dirpath
 'xah-find-files-file-predicate-p
 'xah-find-files-dir-predicate-p)

where xah-find-files-file-predicate-p and xah-find-files-dir-predicate-p are filter functions. They should return t if the file/directory is to be processed.

Each will receive 2 args, fname (short name, no path) and its parent directory parent-dir.

If the function returns true, then that file/directory will be visited.

Here's a example of file name filter:

(defun xah-find-files-file-predicate-p (fname parentdir)
  "return true if fname ends in .html and doesn't begin with xx."
  (and
   (string-match "\\.html$" fname)
   (not (string-match "^xx" fname))
   ))

〔►see Elisp: Regex Tutorial

WARNING: the DIRECTORY-PREDICATE and Dot Directory

WARNING: the DIRECTORY-PREDICATE function will also receive itself (the dot directory), and the parent directory (the dot dot directory).

If you are not careful, it'll be infinite recursion.

So, to solve that problem, you add the default filter find-lisp-default-directory-predicate to yours. Like this:

(defun xah-find-files-dir-predicate-p (fname parentdir)
  "File name predicate. Returns true or false.
Return true if FNAME is not one of the list item (see code) and doesn't begin with xx, and `find-lisp-default-directory-predicate' returns true."
  (and
   (not
    (or
     (string-equal "java8_doc" fname)
     (string-equal "REC-SVG11-20110816" fname)
     (string-equal "clojure-doc-1.8" fname)
     (string-equal "css3_spec_bg" fname)
     (string-equal "css_2.1_spec" fname)
     (string-equal "css_3_color_spec" fname)
     (string-equal "css_transitions" fname)
     (string-equal "dom-whatwg" fname)
     (string-equal "html5_whatwg" fname)
     (string-equal "javascript_ecma-262_5.1_2011" fname)
     (string-equal "javascript_ecma-262_6_2015" fname)
     (string-equal "javascript_es6" fname)
     (string-equal "jquery_doc" fname)
     (string-equal "node_api" fname)
     (string-equal "php-doc" fname)
     (string-equal "python_doc_2.7.6" fname)
     (string-equal "python_doc_3.3.3" fname)
     (string-match "^xx" fname)))
   (find-lisp-default-directory-predicate fname parentdir)))

Note: in unix, directory is considered a special file. So, in emacs doc and other unix doc, the term “file name” may also refer to directory name.

Like it? Buy Xah Emacs Tutorial. Thanks.