option_spec {options}

Specify Option

Description

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.

Usage

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()
)

Arguments

name

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.

default

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.

desc

A written description of the option's effects

option_name, envvar_name

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.

option_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".

envvar_fn

A function to use for parsing environment variable values. Defaults to envvar_eval_or_raw(). For further details see section "Processing Functions".

quoted

A logical value indicating whether the default argument should be treated as a quoted expression or as a value.

eager

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.

envir

An environment in which to search for an options envir object. It is rarely necessary to use anything but the default.

Value

An option_spec object, which is a simple S3 class wrapping a list containing these arguments.

Processing Functions

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)