An option specification outlines the various behaviors of an option. It's default value, related global R option, and related environment variable name, as well as a description. This information defines the operating behavior of the option.
option_spec(
name,
default = bquote(),
desc = NULL,
option_name = get_option_name_fn(envir),
envvar_name = get_envvar_name_fn(envir),
option_fn = function(value, ...) value,
envvar_fn = envvar_eval_or_raw(),
quoted = FALSE,
eager = FALSE,
envir = parent.frame()
)An option_spec object, which is a simple S3 class wrapping a list
containing these arguments.
A string representing the internal name for the option. This is
the short form <option> used within a namespace and relates to, for
example, <package>.<option> global R option.
Either a quoted expression (if parameter quote == TRUE) or
default value for the option. Defaults to an empty expression, indicating
that it is unset. The default value is lazily evaluated, evaluated only
when the option is first requested unless parameter eager == TRUE.
A written description of the option's effects
A character value or function. If a character
value is provided it is used as the corresponding global option name or
environment variable name. If a function is provided it is provided with
the package name and internal option name to derive the global option name.
For example, provided with package "mypkg" and option "myoption", the
function might return global option name "mypkg.myoption" or environment
variable name "R_MYPKG_MYOPTION". Defaults to configured default
functions which fall back to option_name_default and
envvar_name_default, and can be configured using set_option_name_fn
and set_envvar_name_fn.
A function to use for processing an option value before being returned from the opt accessor functions. For further details see section "Processing Functions".
A function to use for parsing environment variable values.
Defaults to envvar_eval_or_raw(). For further details see section
"Processing Functions".
A logical value indicating whether the default argument
should be treated as a quoted expression or as a value.
A logical value indicating whether the default argument should
be eagerly evaluated (upon call), or lazily evaluated (upon first use).
This distinction will only affect default values that rely on evaluation of
an expression, which may produce a different result depending on the
context in which it is evaluated.
An environment in which to search for an options envir object. It is rarely necessary to use anything but the default.
Parameters option_fn and envvar_fn allow for customizing the way values
are interpreted and processed before being returned by opt functions.
envvar_fn
When a value is retrieved from an environment variable, the string value
contained in the environment variable is first processed by envvar_fn.
An envvar_fn accepts only a single positional argument, and should have a
signature such as:
function(value)
option_fn
Regardless of how a value is produced - either retrieved from an environment
variable, option, a stored default value or from a default provided to an
opt accessor function - it is then further processed by option_fn.
The first argument provided to option_fn will always be the retrieved
value. The remaining parameters in the signature should be considered
experimental. In addition to the value, the arguments provided to opt(),
as well as an additional source parameter from opt_source() may be
used.
Stable
function(value, ...)
Experimental
function(value, x, default, env, ..., source)