The R Project SVN R

% File src/library/base/man/Sys.glob.Rd
% Part of the R package, http://www.R-project.org
% Copyright 1995-2009 R Core Development Team
% Distributed under GPL 2 or later

\name{Sys.glob}
\alias{Sys.glob}
\title{Wildcard Expansion on File Paths}
\description{
  Function to do wildcard expansion (also known as \sQuote{globbing}) on
  file paths.
}
\usage{
Sys.glob(paths, dirmark = FALSE)
}
\arguments{
  \item{paths}{character vector of patterns for relative or absolute
    filepaths.  Missing values will be ignored.}
  \item{dirmark}{logical: should matches to directories from patterns
    that do not already end in \code{/}
#ifdef windows
    or \code{\\}
#endif
    have a slash appended?  May not be supported on all platforms.}
}
\details{
#ifdef unix
  This expands wildcards in file paths.  For precise details, see your
  system's documentation on the \code{glob} system call.  There is a
  POSIX 1003.2 standard (see
  \url{http://www.opengroup.org/onlinepubs/009695399/functions/glob.html})
  but some OSes will go beyond this.  The \R implementation will always
  do tilde-expansion (see \code{\link{path.expand}}).

  All systems should interpret \code{*} (match zero or more characters),
  \code{?} (match a single character) and (probably) \code{[} (begin a
  character class or range).  If a filename starts with \code{.} this
  must be matched explicitly.  By default paths ending in \code{/} will
  be accepted and matched only to directories.

  The rest of these details are indicative (and based on the POSIX
  standard).
  
  \code{[} begins a character class.  If the first character in
  \code{[...]} is not \code{!}, this is a character class which matches
  a single character against any of the characters specified.  The class
  cannot be empty, so \code{]} can be included provided it is first.  If
  the first character is \code{!}, the character class matches a single
  character which is \emph{none} of the specified characters.
  
  Character classes can include ranges such as \code{[A-Z]}: include
  \code{-} as a character by having it first or last in a class.  (The
  interpretation of ranges should be locale-specific, so the example is
  not a good idea in an Estonian locale.)

  One can remove the special meaning of \code{?}, \code{*}  and
  \code{[} by preceding them by a backslash (except within a
  character class).
#endif
#ifdef windows
  The \code{glob} system call is not part of Windows, and we supply a
  partial emulation.

  Wildcards are \code{*} (match zero or more characters) and \code{?} (match
  a single character).  If a filename starts with \code{.} this must be
  matched explicitly.

  In addition, \code{[} begins a character class.  If the first
  character in \code{[...]} is not \code{!}, this is a character class
  which matches a single character against any of the characters
  specified.  The class cannot be empty, so \code{]} can be included
  provided it is first.  If the first character is \code{!}, the
  character class matches a single character which is \emph{none} of the
  specified characters.
  
  Character classes can include ranges such as \code{[A-Z]}: include
  \code{-} as a character by having it first or last in a class.  (In the
  current implementation ranges are in numeric order of Unicode points.)

  One can remove the special meaning of \code{?}, \code{*}  and
  \code{[} by preceding them by a backslash (except within a
  character class).  Note that on Windows \code{?} and \code{*} are not
  valid in file names, so this is mainly for consistency with other
  platforms.

  File paths in Windows are interpreted with separator \code{\\} or
  \code{/}.  Paths with a drive but relative (such as \code{c:foo\\bar})
  are tricky, but an attempt is made to handle them correctly.  As from
  \R 2.9.2 an attempt is made to handle UNC paths starting with a double
  backslash.
#endif
}
\value{
  A character vector of matched file paths.  The order is
  system-specific (but in the order of the elements of \code{paths}):
#ifdef unix
  it is normally collated in either the current locale or in byte (ASCII) order.
#endif
#ifdef windows
  on Windows collation is in the order of Unicode points.
#endif
  
  Directory errors are normally ignored, so the matches are to
  accessible file paths (but not necessarily accessible files).
}
\seealso{
  \code{\link{path.expand}}.

  \link{Quotes} for handling backslashes in character strings.
}
\examples{
\dontrun{
Sys.glob(file.path(R.home(), "library", "*", "R", "*.rdx"))
}}
\keyword{utilities}
\keyword{file}