########################################################################/**
# @RdocFunction findFiles
#
# @title "Finds one or several files in multiple directories"
#
# \description{
# @get "title".
# }
#
# @synopsis
#
# \arguments{
# \item{pattern}{A regular expression file name pattern to match.}
# \item{paths}{A @character @vector of paths to be searched.}
# \item{recursive}{If @TRUE, the directory structure is searched
# breath-first, in lexicographic order.}
# \item{firstOnly}{If @TRUE, the method returns as soon as a matching
# file is found, otherwise not.}
# \item{allFiles}{If @FALSE, files and directories starting with
# a period will be skipped, otherwise not.}
# \item{...}{Arguments passed to @see "base::list.files".}
# }
#
# \value{
# Returns a @vector of the full pathnames of the files found.
# }
#
# \section{Paths}{
# The \code{paths} argument may also contain paths specified as
# semi-colon (\code{";"}) separated paths, e.g.
# \code{"/usr/;usr/bin/;.;"}.
# }
#
# \section{Windows Shortcut links}{
# If package \pkg{R.utils} is available and loaded , Windows Shortcut links (*.lnk)
# are recognized and can be used to imitate links to directories
# elsewhere. For more details, see @see "R.utils::filePath".
# }
#
# @author "HB"
#
# @keyword file
# @keyword IO
# @keyword internal
#**/#######################################################################
findFiles <- function(pattern=NULL, paths=NULL, recursive=FALSE, firstOnly=TRUE, allFiles=TRUE, ...) {
# To please R CMD check
filePath <- NULL; rm(list="filePath");
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Local functions
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
splitPaths <- function(paths, ...) {
if (length(paths) == 0)
return(NULL);
# If in format "path1; path2;path3", split it to multiple strings.
paths <- unlist(strsplit(paths, split=";"));
paths <- gsub("[ \t]*$", "", gsub("^[ \t]*", "", paths));
paths <- paths[nchar(paths) > 0];
if (length(paths) == 0)
return(NULL);
paths;
} # splitPaths()
# Checks if a package is loaded or not (cut'n'paste from R.utils)
isPackageLoaded <- function(package, version=NULL, ...) {
s <- search();
if (is.null(version)) {
s <- sub("_[0-9.-]*", "", s);
} else {
package <- paste(package, version, sep="_");
}
pattern <- sprintf("package:%s", package);
(pattern %in% s);
}
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Validate arguments
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Argument 'paths':
paths <- splitPaths(paths);
if (is.null(paths))
paths <- ".";
# Argument 'pattern':
if (!is.null(pattern))
pattern <- as.character(pattern);
# Argument 'recursive':
recursive <- as.logical(recursive);
# Argument 'firstOnly':
firstOnly <- as.logical(firstOnly);
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Prepare list of paths to be scanned
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
hasRutilsLoaded <- isPackageLoaded("R.utils");
## hasRutils <- suppressWarnings(require(R.utils, quietly=TRUE));
# Don't search the same path twice
paths <- unique(paths);
# Don't search non-existing paths
for (kk in seq_along(paths)) {
path <- paths[kk];
# Example any '~':s
path <- file.path(dirname(path), basename(path));
path <- gsub("^[.][/\\]", "", path);
# Follow Windows shortcut links?
if (hasRutilsLoaded)
path <- filePath(path, expandLinks="any");
# Does the path exist and is it a directory
# Note, isdir is TRUE for directories, FALSE for files,
# *and* NA for non-existing files, e.g. items found by
# list.files() but are broken Unix links.
isDirectory <- identical(file.info(path)$isdir, TRUE);
if (!file.exists(path) || !isDirectory)
path <- NA;
paths[kk] <- path;
}
if (length(paths) > 0)
paths <- paths[!is.na(paths)];
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
# Search for files
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
pathnames <- c();
for (path in paths) {
files <- list.files(path, all.files=allFiles, full.names=TRUE);
# Exclude listings that are neither files nor directories
files <- gsub("^[.][/\\]", "", files);
files <- files[nchar(files) > 0];
if (length(files) > 0) {
excl <- (basename(files) %in% c(".", "..", "/", "\\"));
files <- files[!excl];
}
# Nothing to do?
if (length(files) == 0)
next;
# Expand Windows shortcut links?
files0 <- files;
if (hasRutilsLoaded) {
# Remember these
files <- sapply(files, FUN=filePath, expandLinks="any", USE.NAMES=FALSE);
}
# Keep only existing files and directories
ok <- sapply(files, FUN=function(file) {
(file.exists(path) && !is.na(file.info(file)$isdir));
}, USE.NAMES=FALSE);
files <- files[ok];
files0 <- files0[ok];
# Nothing to do?
if (length(files) == 0)
next;
# First search the files, then the directories, so...
# Note, isdir is TRUE for directories, FALSE for files,
# *and* NA for non-existing files, e.g. items found by
# list.files() but are broken Unix links.
isDir <- sapply(files, FUN=function(file) {
identical(file.info(file)$isdir, TRUE);
file.info(file)$isdir;
}, USE.NAMES=FALSE);
# In case some files are non-accessible, exclude them
ok <- (!is.na(isDir));
files <- files[ok];
files0 <- files0[ok];
isDir <- isDir[ok];
# Nothing to do?
if (length(files) == 0)
next;
# Directories and files in lexicographic order
dirs <- files[isDir];
files <- files[!isDir];
files0 <- files0[!isDir];
# Keep only files that match the filename pattern
# of the non-expanded filename.
if (!is.null(pattern)) {
keep <- grep(pattern, basename(files0));
files <- files[keep];
}
if (length(files) > 0) {
files <- sort(files);
if (firstOnly)
return(files[1]);
# Store results
pathnames <- c(pathnames, files);
}
# Search directories recursively?
if (recursive) {
if (length(dirs) == 0)
next;
for (dir in sort(dirs)) {
files <- findFiles(pattern=pattern, paths=dir, recursive=recursive,
firstOnly=firstOnly, ...);
if (length(files) > 0 && firstOnly)
return(files[1]);
pathnames <- c(pathnames, files);
}
}
} # for (path ...)
pathnames;
} # findFiles()
############################################################################
# HISTORY:
# 2013-03-18 [HB]
# o Internal isPackageLoaded() no longer uses defunct manglePackageName().
# 2008-02-21 [HB]
# o Added an internal generic isPackageLoaded() function.
# 2008-02-20 [KH]
# o Replaced require("R.utils") with a "isLoaded()" feature.
# 2008-02-14
# o Added argument 'allFiles=TRUE' to findFiles().
# 2007-09-17
# o ROBUSTNESS: Now findFiles() are robust against broken Unix links.
# 2007-08-30
# o BUG FIX: Pattern matching was done on expanded filenames, whereas they
# should really be done on the non-expanded ones. This, only applies to
# Windows shortcuts, but it is not the destination file that is of
# interest, but the name of the shortcut file.
# o BUG FIX: The recent update was not grep():ing correctly; forgot to
# extract the basename().
# 2007-08-27
# o Now findFiles(..., recursive=TRUE) does a breath-first search in
# lexicographic order.
# o Now findFiles() don't search replicated directories.
# 2006-11-01
# o Removed usage of R.utils for now.
# 2006-03-14
# o Created from findCdf.R.
############################################################################
