| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |
Arguments: function directory &key filter prune-directories include-directories (recurse t) (file-type :pathname) (follow-symbolic-links t) relative
In earlier releases, 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-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.
| Allegro CL version 8.2 Unrevised from 8.1 to 8.2. 8.1 version |