% 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 = get_Rscript_filename(),
  usage = FALSE, debug = FALSE)
}
\arguments{
\item{spec}{The getopt specification, or spec of what options are considered
valid.  The specification must be either a 4-5 column \link{matrix}, or a
\link{character} \link{vector} coercible into a 4 column \link{matrix} using
\link{matrix}(x,ncol=4,byrow=TRUE) command.  The \link{matrix}/\link{vector}
contains:

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

Column 2: \emph{short flag} alias of Column 1.  A single-\link{character}
string.

Column 3: \emph{Argument} mask of the \emph{flag}.  An \link{integer}.
Possible values: 0=no argument, 1=required argument, 2=optional argument.

Column 4: Data type to which the \emph{flag}'s argument shall be cast using
\link{storage.mode}.  A multi-\link{character} string.  This only considered
for same-row Column 3 values of 1,2.  Possible values: \link{logical},
\link{integer}, \link{double}, \link{complex}, \link{character}.
If \link{numeric} is encountered then it will be converted to 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 ``Description'' section for definitions.}

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

If R was invoked directly via the ``R'' command, this corresponds to all
arguments passed to R after the ``--args'' flag.

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

Read about \link{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 TRUE, argument \emph{opt} will be ignored and a usage
statement (character string) will be generated and returned from \emph{spec}.}

\item{debug}{This is used internally to debug the getopt() function itself.}
}
\description{
getopt is primarily intended to be used with ``\link{Rscript}''.  It
facilitates writing ``\#!'' shebang scripts that accept short and long
flags/options.  It can also be used from ``R'' directly, but is probably less
useful in this context.
}
\details{
getopt() returns a \link{list} data structure containing \link{names} of the
flags that were present in the \link{character} \link{vector} passed in under
the \emph{opt} argument.  Each value of the \link{list} is coerced to the
data type specified according to the value of the \emph{spec} argument.  See
below for details.

Notes on naming convention:

1. An \emph{option} is one of the shell-split input strings.

2. 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}.

3. An \emph{argument} is a type of \emph{option}, and is the value associated
with a flag.

4. A \emph{long flag} is a type of \emph{flag}, and begins with the string
``--''.  If the \emph{long flag} has an associated \emph{argument}, it may be
delimited from the \emph{long flag} by either a trailing \emph{=}, or may be
the subsequent \emph{option}.

5. A \emph{short flag} is a type of \emph{flag}, and begins with the string
``-''.  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 ``-'', but only the final \emph{short flag} is able
to have a corresponding \emph{argument}.

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

Features available in \code{getopt} unavailable in \code{optparse}

1. As well as allowing one to specify options that take either
     no argument or a required argument like \code{optparse},
   \code{getopt} also allows one to specify option with an optional argument.

Some features implemented in \code{optparse} package unavailable in \code{getopt}

1. Limited support for capturing positional arguments after the optional arguments
when \code{positional_arguments} set to TRUE in \code{parse_args}

2. Automatic generation of an help option and printing of help text when encounters an "-h"

3. Option to specify default arguments for options as well the
   variable name to store option values

There is also new package \code{argparse} introduced in 2012 which contains
all the features of both getopt and optparse but which has a dependency on
Python 2.7 or 3.2+ and has not been used in production since 2008 or 2009
like the getopt and optparse packages.

Some Features unlikely to be implemented in \code{getopt}:

1. Support for multiple, identical flags, e.g. for "-m 3 -v 5 -v", the
trailing "-v" overrides the preceding "-v 5", result is v=TRUE (or equivalent
typecast).

2. Support for multi-valued flags, e.g. "--libpath=/usr/local/lib
--libpath=/tmp/foo".

3. Support for lists, e.g. "--define os=linux --define os=redhat" would
set result$os$linux=TRUE and result$os$redhat=TRUE.

4. Support for incremental, argument-less flags, e.g. "/path/to/script
-vvv" should set v=3.

5. Support partial-but-unique string match on options, e.g. "--verb" and
"--verbose" both match long flag "--verbose".

6. No support for mixing in positional arguments or extra arguments that
don't match any options.  For example, you can't do "my.R --arg1 1 foo bar
baz" and recover "foo", "bar", "baz" as a list.  Likewise for "my.R foo
--arg1 1 bar baz".
}
\examples{

#!/path/to/Rscript
library('getopt')
# get options, using the spec as defined by the enclosed list.
# we read the options from the default: commandArgs(TRUE).
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=4)
opt = getopt(spec)

# if help was asked for print a friendly message 
# and exit with a non-zero error code
if ( !is.null(opt$help) ) {
  cat(getopt(spec, usage=TRUE))
  q(status=1)
}

# set some reasonable defaults for the options that are needed,
# but 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   = 10    }
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(paste(rnorm(opt$count,mean=opt$mean,sd=opt$sd),collapse="\\n"))
cat("\\n")

# signal success and exit.
# q(status=0)

}
\seealso{
\code{\link{getopt}}
}
\author{
Allen Day
}
\keyword{data}
