map-over-directory

Arguments: function directory &key filter prune-directories include-directories (recurse t) (file-type :pathname) (follow-symbolic-links t) relative

Documentation Note

Some earlier versions of this documentation did not make clear that when the include-directories keyword argument is specified non-nil, the argument directory would be one of the objects mapped over. Also, an error in the implementation (now fixed) meant that function was (incorrectly) not applied to directory when include-directories was non-nil and file-type was :string.

The relative keyword argument has been present for some time but was undocumented until a March, 2016 documentation update.

This function can be used to walk a directory structure rooted at directory. function is applied to each file in the directory. directory can contain wildcards. This function is called for the side effects of applying function to files (and optionally directories) in directory. No useful value is returned.

If filter is non-nil, then its value should be a function used to filter out candidate files and directories. The filter function takes one argument, a pathname, and returns a true value if function should be called on this file. It does not prevent recursion if the pathname is a directory.

The argument file-type controls whether a pathname object or a namestring is passed to function. The allowable values are :pathname (the default) and :string. If the directory of interest is very large, specifying :string (and ensuring that function works as desired with a string argument) may significantly reduce consing (i.e. generation of garbage).

If include-directories is true, then function also gets called on directories, including the argument directory.

If recurse is true (the default), then map-over-directory descends into subdirectories and maps over the files (or files and directories) in them. Note that this argument and include-directories are disjoint. This argument controls whether the contents of subdirectories are mapped over. include-directories controls whether directories are passed to function or not.

prune-directories, if specified, must be a list of strings naming directories with no punctuation (i.e. no slashes) or a predicate function object (not a function name, i.e. a symbol or function spec) accepting one argument of the type specified by file-type. If the value is a list, any directory encountered during the operation whose name is on the list will be ignored (neither it nor its contents nor its subdirectories will be mapped over). If the value is a predicate function, a directory for which the predicate returns true will be ignored. For example, suppose subdirectories foo and bar each have a subdirectory CVS. Then either

:prune-directories '("CVS")

or

:prune-directories '(lambda (string)
                      (if (string= "CVS" string) t))

will cause foo/CVS and bar/CVS both to be ignored (the second example assumes file-type is :string). There is no way to have foo/CVS considered and bar/CVS ignored with this argument.

The follow-symbolic-links argument determines what is done when a symbol link to a directory is encountered. If follow-symbolic-links is true, then the link is followed and all elements of the directory are acted upon. If follow-symbolic-links is nil, then the symbolic link is treated as a file, and passed to the function, but the files in the directory are not. This argument provides more control over the behavior of this function, which might be important when the function does something like deleting files. The default is t, which preserves the behavior of earlier releases.

The follow-symbolic-links argument is ignored on Windows, where there are no symbolic links.

The relative argument, if true, causes the pathnames passed to function to be relative to the directory argument, rather than absolute. For example suppose the directory /usr/mydir/foo.d/ contains three files, foo1, foo2, and foo3, then we have the following behavior:

cl-user(2): (map-over-directory
	     (lambda (p) (print p))
	     "/usr/mydir/foo.d/")

#P"/usr/mydir/foo.d/foo2" 
#P"/usr/mydir/foo.d/foo1" 
#P"/usr/mydir/foo.d/foo3" 
nil
cl-user(3): (map-over-directory
	     (lambda (p) (print p))
	     "/usr/mydir/foo.d/"
	     :relative t)

#P"foo2" 
#P"foo1" 
#P"foo3" 
nil
cl-user(4): 

Copyright (c) 1998-2019, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.2 page.
Created 2012.5.30.