% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/getopt.R
\name{getopt}
\alias{getopt}
\alias{getopt-package}
\title{C-like getopt behavior}
\usage{
getopt(
  spec = NULL,
  opt = NULL,
  command = getfile(),
  usage = FALSE,
  debug = FALSE,
  operand = "after--only"
)
}
\arguments{
\item{spec}{The getopt specification, or spec of what options are considered
valid.  The specification must be either a 4-5 column matrix, a 4-5 column data frame, or a
character vector coercible into a 4 column matrix using
\code{matrix(x, ncol = 4L, byrow = TRUE)} command.  The matrix/vector
contains:

Column 1: the \emph{long flag} name.  A multi-character string.

Column 2: \emph{short flag} alias of Column 1.  A single-character string.
May be \code{NA_character_} if there is no short flag.

Column 3: \emph{Action} of the \emph{flag}.  A string.
Possible values:
\itemize{
\item \code{"append"} (flag takes a required argument; appends it to a vector each time the flag is used)
\item \code{"count"} (flag takes no argument; stores count of how many times the flag was present)
\item \code{"store_true"} (flag takes no argument; stores \code{TRUE})
\item \code{"store_false"} (flag takes no argument; stores \code{FALSE})
\item \code{"store"} (flag takes a required argument)
\item \code{"store_optional"} (flag takes an optional argument but if none present stores \code{TRUE})
}

For backwards compatibility \code{0}, \code{1}, \code{2} are accepted as aliases for
\code{"store_true"}, \code{"store"}, \code{"store_optional"} respectively.

Column 4: Data type to which the \emph{flag}'s argument shall be cast using
\code{\link[=storage.mode]{storage.mode()}}.  A multi-character string.
Only used when an action took an argument.
Possible values: "logical", "integer", "double", "complex", "character".
"numeric" is treated as an alias for "double".

Column 5 (optional): A brief description of the purpose of the option.

The terms \emph{option}, \emph{flag}, \emph{long flag}, \emph{short flag},
and \emph{argument} have very specific meanings in the context of this
document.  Read the \dQuote{Details} section of \code{\link[=getopt]{getopt()}} for definitions.}

\item{opt}{This defaults to the return value of \code{commandArgs(TRUE)} unless
\code{argv} is in the global environment in which case it uses that instead
(this is for compatibility with \code{littler}).

If R was invoked directly via the \code{R} command, this corresponds to all
arguments passed to R after the \code{--args} flag.

If R was invoked via the \code{Rscript} command, this corresponds to all
arguments after the name of the R script file.

Read about \code{\link[=commandArgs]{commandArgs()}} and \link{Rscript} to learn more.}

\item{command}{The string to use in the usage message as the name of the
script.  See argument \emph{usage}.}

\item{usage}{If \code{TRUE}, argument \code{opt} will be ignored and a usage
statement (character string) will be generated and returned from \code{spec}.}

\item{debug}{This is used internally to debug the \code{getopt()} function itself.}

\item{operand}{Controls how positional arguments (operands) are handled.
\itemize{
\item \code{"after--only"} (the default) only collects operands that appear after a \code{"--"} separator.
\item \code{"strict"} (in addition to operands that appear after a \code{"--"} separator) collects tokens that do not look
like flags and were not consumed as a flag argument, while still erroring on
unrecognized flags.
}

Operands are stored in the \code{"operand"} attribute of the
result and can be retrieved with \code{\link[=getoperand]{getoperand()}}.}
}
\value{
\code{\link[=getopt]{getopt()}} returns a list data structure containing names of the
flags that were present in the character vector passed in under
the \code{opt} argument.  Each value of the list is coerced to the
data type specified according to the value of the \code{spec} argument.  See
the \dQuote{Details} section for more information.
Any positional arguments (operands) are stored in its \code{"operand"} attribute
and can also be accessed by \code{\link[=getoperand]{getoperand()}}.
}
\description{
\code{getopt} is primarily intended to be used with \code{Rscript}.  It
facilitates writing \verb{#!} shebang scripts that accept short and long
flags/options.  It can also be used from \code{R} directly, but is probably less
useful in this context.
}
\details{
Notes on naming convention:
\enumerate{
\item An \emph{option} is one of the shell-split input strings.
\item A \emph{flag} is a type of \emph{option}.  a \emph{flag} can be defined as
having no \emph{argument} (defined below), a required \emph{argument}, or an
optional \emph{argument}.
\item An \emph{argument} is a type of \emph{option}, and is the value associated
with a flag.
\item A \emph{long flag} is a type of \emph{flag}, and begins with the string
\verb{--}.  If the \emph{long flag} has an associated \emph{argument}, it may be
delimited from the \emph{long flag} by either a trailing \code{=}, or may be
the subsequent \emph{option}.
\item A \emph{short flag} is a type of \emph{flag}, and begins with the string
\code{-}.  If a \emph{short flag} has an associated \emph{argument}, it is the
subsequent \emph{option}.  \emph{short flags} may be bundled together,
sharing a single leading \code{-}, but only the final \emph{short flag} is able
to have a corresponding \emph{argument}.
}

Many users wonder whether they should use the \code{getopt} package, \code{optparse} package,
or \code{argparse} package.
Here is some of the major differences:

Features available in \code{getopt} unavailable in \code{optparse}
\enumerate{
\item \code{getopt} allows one to specify options with an optional argument.
\item Long flags may be abbreviated as long as the abbreviation is unique,
e.g. \code{--verb} matches \code{--verbose} if no other long flag starts with \code{verb}.
}

Some features implemented in the \code{optparse} package unavailable in \code{getopt}
\enumerate{
\item Support for capturing positional arguments after the optional arguments
when \code{positional_arguments} set to \code{TRUE} in \code{optparse::parse_args()}
\item Automatic generation of an help option and printing of help text when encounters an \code{-h}
\item Option to specify default arguments for options as well the
variable name to store option values
}

There is also package \code{argparse} supports
all the features of both getopt and optparse (plus more)

Some Features unlikely to be implemented in \code{getopt}:
\enumerate{
\item Support for lists, e.g. \verb{--define os=linux --define os=redhat} would
set \code{result$os$linux=TRUE} and \code{result$os$redhat=TRUE}.
}
}
\examples{
#!/path/to/Rscript
library('getopt')
# get options, using the spec as defined by the matrix
spec <- matrix(c(
  'verbose', 'v', 2, "integer",
  'help'   , 'h', 0, "logical",
  'count'  , 'c', 1, "integer",
  'mean'   , 'm', 1, "double",
  'sd'     , 's', 1, "double"
), byrow = TRUE, ncol = 4L)
opt <- getopt(spec)

# if help was asked for print a friendly message and exit
if (isTRUE(opt$help)) {
  cat(getusage(spec))
  q(status = 0)
}

# set reasonable defaults for options that were not specified
if (is.null(opt$mean)) opt$mean <- 0
if (is.null(opt$sd)) opt$sd <- 1
if (is.null(opt$count)) opt$count <- 10L
if (is.null(opt$verbose)) opt$verbose <- FALSE

# print some progress messages to stderr, if requested
if (opt$verbose) write("writing...", stderr())

# do some operation based on user input
cat(rnorm(opt$count, mean = opt$mean, sd = opt$sd), sep = "\n")
}
\author{
Allen Day and Trevor L. Davis
}
\keyword{data}
