% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/optparse.R
\name{make_option}
\alias{make_option}
\alias{add_option}
\title{Functions to enable our OptionParser to recognize specific command line
options.}
\usage{
make_option(
  opt_str,
  action = NULL,
  type = NULL,
  dest = NULL,
  default = NULL,
  help = "",
  metavar = NULL,
  callback = NULL,
  callback_args = NULL,
  const = NULL,
  required = FALSE
)

add_option(
  object,
  opt_str,
  action = NULL,
  type = NULL,
  dest = NULL,
  default = NULL,
  help = "",
  metavar = NULL,
  callback = NULL,
  callback_args = NULL,
  const = NULL,
  required = FALSE
)
}
\arguments{
\item{opt_str}{A character vector containing the string of the desired long
flag comprised of \verb{--} followed by a non-dash character (and optionally more characters), and
optionally a string of the desired short flag comprised of the
\code{-} followed by a single non-dash character.  We don't allow \code{=} or whitespace characters in flags.}

\item{action}{A character string describing the action \code{optparse} should take when it encounters an option. One of:
\itemize{
\item \code{"append"}: appends each occurrence's value to \code{default} (or to an empty vector if \code{default} is \code{NULL}). Returns \code{NULL} if never seen and \code{default} is \code{NULL}.
\item \code{"callback"}: stores the return value of the \code{callback} function.
\item \code{"count"}: counts the number of times the flag is seen and adds it to \code{default} (treated as \code{0L} if not supplied). Returns \code{NULL} if never seen and no \code{default} was supplied.
\item \code{"store"} (default): stores the specified following value.
\item \code{"store_const"}: stores \code{const} if the flag is seen, otherwise \code{default}. Returns \code{NULL} if the flag is not seen and \code{default} is \code{NULL}.
\item \code{"store_true"}: stores \code{TRUE} if the option is found.
\item \code{"store_false"}: stores \code{FALSE} if the option is found.
}

If \code{callback} is not \code{NULL} the default action is \code{"callback"} otherwise it is \code{"store"}.}

\item{type}{A character string specifying which data type to store: \code{"logical"}, \code{"integer"}, \code{"double"}, \code{"complex"}, or \code{"character"} (\code{"numeric"} is an alias for \code{"double"}). Defaults:
\itemize{
\item if \code{action == "count"} then \code{"integer"}
\item if \code{action \%in\% c("store_false", "store_true")} then \code{"logical"}
\item if \code{action == "store"} and \code{default} is not \code{NULL} then \code{typeof(default)}else if \code{default} is \code{NULL} then \code{"character"}
}}

\item{dest}{A character string specifying what field in the list returned by \code{\link[=parse_args]{parse_args()}} should \code{optparse} store the option value. Default is derived from the long flag in \code{opt_str}.}

\item{default}{The default value \code{optparse} should use if it does not find the option on the command line.}

\item{help}{A character string describing the option, used by \code{\link[=print_help]{print_help()}} in generating a usage message. \code{"\%default"} will be substituted by the value of \code{default}.}

\item{metavar}{A character string that stands in for the option argument when printing help text. Default is the value of \code{dest}.}

\item{callback}{A function that executes after the option value is fully parsed. Its return value is assigned to the option. Arguments are: the option S4 object, the long flag string, the value of the option, the parser S4 object, and \code{...}.}

\item{callback_args}{A list of additional arguments passed to \code{callback} (via \code{\link[=do.call]{do.call()}}).}

\item{const}{The value to store when \code{action = "store_const"} and the flag is seen. Ignored for all other actions.}

\item{required}{If \code{TRUE}, \code{\link[=parse_args]{parse_args()}} will throw an error if this option is not provided on the command line.
\strong{Note:} Required options are generally considered bad form because users
expect \emph{options} to be \emph{optional}, and thus they should be avoided when possible.}

\item{object}{An instance of the \code{OptionParser} class}
}
\value{
Both \code{\link[=make_option]{make_option()}} and \code{\link[=add_option]{add_option()}} return instances of
class \code{OptionParserOption}.
}
\description{
\code{\link[=add_option]{add_option()}} adds a option to a prexisting \code{OptionParser} instance
whereas \code{\link[=make_option]{make_option()}} is used to create a list of
\code{OptionParserOption} instances that will be used in the
\code{option_list} argument of the \code{OptionParser} function to create a
new \code{OptionParser} instance.
}
\section{Errors}{

The following classed errors may be thrown:
\itemize{
\item \code{optparse_option_error}: invalid option definition (bad flag string,
unrecognized action, etc.).
\itemize{
\item \code{optparse_option_conflict_error}: duplicate flag detected when
adding an option to a parser.
}
}
}

\examples{

   make_option("--longflag")
   make_option(c("-l", "--longflag"))
   make_option("--integer", type = "integer", default = 5)
   make_option("--integer", default = as.integer(5))  # same as previous

   # examples from package vignette
   make_option(c("-v", "--verbose"), action = "store_true", default = TRUE,
       help = "Print extra output [default]")
   make_option(c("-q", "--quietly"), action = "store_false",
     dest = "verbose", help = "Print little output")
   make_option(c("-c", "--count"), type = "integer", default = 5,
       help = "Number of random normals to generate [default \%default]",
       metavar = "number")
   make_option("--generator", default = "rnorm",
       help = "Function to generate random deviates [default \"\%default\"]")
   make_option("--mean", default = 0,
       help = "Mean if generator == \"rnorm\" [default \%default]")
   make_option("--sd", default = 1, metavar = "standard deviation",
       help = "Standard deviation if generator == \"rnorm\" [default \%default]")

}
\references{
Python's \code{optparse} library, which inspires this package,
is described here: \url{https://docs.python.org/3/library/optparse.html}
}
\seealso{
\code{\link[=parse_args]{parse_args()}} \code{\link[=OptionParser]{OptionParser()}}
}
