Specify Option

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),
  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.

envvar_fn

A function to use for parsing environment variable values. Defaults to envvar_eval_or_raw().

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.