% File src/library/tools/man/rtags.Rd
% Part of the R package, https://www.R-project.org
% Copyright 2008-2015 R Core Team
% Distributed under GPL 2 or later

\name{rtags}
\alias{rtags}
\title{ An Etags-like Tagging Utility for R }
\description{
  \code{rtags} provides etags-like indexing capabilities for R code,
  using R's own parser.
}
\usage{
rtags(path = ".", pattern = "\\\\.[RrSs]$",
      recursive = FALSE,
      src = list.files(path = path, pattern = pattern,
                       full.names = TRUE,
                       recursive = recursive),
      keep.re = NULL,
      ofile = "", append = FALSE,
      verbose = getOption("verbose"),
      type = c("etags", "ctags"))
}

\arguments{
  \item{path, pattern, recursive}{
    Arguments passed on to \code{\link{list.files}} to determine the
    files to be tagged.  By default, these are all files with extension
    \code{.R}, \code{.r}, \code{.S}, and \code{.s} in the current
    directory.  These arguments are ignored if \code{src} is specified.
  }
  \item{src}{
    A vector of file names to be indexed.
  }
  \item{keep.re}{ A regular expression further restricting \code{src}
    (the files to be indexed).  For example, specifying
    \code{keep.re = "/R/[^/]*\\\\.R$"} will only retain files with
    extension \code{.R} inside a directory named \code{R}.
  }

  \item{ofile}{ Passed on to \code{\link{cat}} as the \code{file}
    argument; typically the output file where the tags will be written
    (\code{"TAGS"} or \code{"tags"} by convention).  By default, the
    output is written to the R console (unless redirected).
  }
  \item{append}{ Logical, indicating whether the output should overwrite
    an existing file, or append to it.
  }
  \item{verbose}{ Logical.  If \code{TRUE}, file names are echoed to the
    R console as they are processed.
  }
  \item{type}{ Character string specifying whether emacs style
    (\code{"etags"}) or vi style (\code{"ctags"}) tags are to be
    generated.
  }
}

\details{
  Many text editors allow definitions of functions and other language
  objects to be quickly and easily located in source files through a
  tagging utility.  This functionality requires the relevant source
  files to be preprocessed, producing an index (or tag) file containing
  the names and their corresponding locations.  There are multiple tag
  file formats, the most popular being the vi-style ctags format and the
  and emacs-style etags format.  Tag files in these formats are usually
  generated by the \code{ctags} and \code{etags} utilities respectively.
  Unfortunately, these programs do not recognize R code syntax.  They do
  allow tagging of arbitrary language files through regular expressions,
  but this too is insufficient.

  The \code{rtags} function is intended to be a tagging utility for R
  code.  It parses R code files (using R's parser) and produces tags in
  both etags and ctags formats.  The support for vi-style ctags is
  rudimentary, and was adapted from a patch by Neal Fultz; see
  \PR{17214}.

  It may be more convenient to use the command-line wrapper script
  \code{R CMD rtags}.
}

\references{
  \url{https://en.wikipedia.org/wiki/Ctags},
  \url{https://www.gnu.org/software/emacs/manual/html_node/emacs/Tags-Tables.html}
}
\author{Deepayan Sarkar}
\seealso{ \code{\link{list.files}}, \code{\link{cat}} }
\examples{

\dontrun{
rtags("/path/to/src/repository",
      pattern = "[.]*\\\\.[RrSs]$",
      keep.re = "/R/",
      verbose = TRUE,
      ofile = "TAGS",
      append = FALSE,
      recursive = TRUE)
}

}
\keyword{programming}
\keyword{utilities}