OptionValue

OptionValue[name]

gives the value of name in options matched by OptionsPattern.

OptionValue[f,name]

gives the value of name for options associated with the head f.

OptionValue[f,opts,name]

extracts option values from the explicit list of rules opts.

OptionValue[,{name1,name2,}]

extracts several option values.

Details

  • OptionValue[name] is equivalent to OptionValue[f,name], where f is the head of the left-hand side of the transformation rule in which OptionValue[name] appears.
  • OptionValue[f,name] and OptionValue[name] will use values from the first OptionsPattern object that appears as an argument of f.
  • In OptionValue[f,opts,name], only the explicit list opts and the defaults derived from f will be considered.
  • In OptionValue[f,opts,name], f can be a symbol, a rule, or a list of symbols and rules specifying default values. Each symbol s in f is equivalent to Options[s]. If the same option name is specified multiple times, the first specification determines the default.
  • OptionValue[f,opts,name,Hold] returns the option value with Hold wrapped around it.
  • OptionValue[Automatic,Automatic,name,Hold] is equivalent to OptionValue[name], except that the option value is returned with Hold wrapped around it.
  • OptionValue ignores contexts when comparing option names and treats the symbol s and the string SymbolName[s] interchangeably.

Examples

open allclose all

Basic Examples  (1)

Define default option values for the function f:

Define f, allowing options to be given:

Use f with an explicit option setting:

Use f with options taken to have their default values:

Scope  (4)

Retrieve several option values at once:

Use an explicit list of options:

Define a transformation rule using multiple OptionsPattern constructs:

OptionValue[a] is treated as OptionValue[f,a] because it is the outer head:

OptionValue tracks where a particular option was specified:

Use Hold in the fourth argument to return the unevaluated forms of options using RuleDelayed:

Without the Hold, the current value of $Assumptions would be returned:

Applications  (2)

Define the default option values for a function f:

Implement f using a helper function fCore, but still inherit defaults from f:

The default option value of f is honored:

An explicit option setting takes precedence:

Define two functions with options:

Define a function h that uses both sets of options, giving preference to the defaults of g:

Properties & Relations  (4)

Contexts are ignored when comparing option names:

A string and a symbol are treated interchangeably:

OptionValue checks that all options requested appear in the defaults:

For simple cases, OptionValue[f,opts,name] is similar to name/.opts/.Options[f]:

However, OptionValue performs additional normalization to ensure rules are correctly applied:

Possible Issues  (1)

Define a transformation rule where OptionsPattern only appears inside a different function:

OptionValue[a] does not work because OptionsPattern is not an argument of f:

Introduced in 2007
 (6.0)