Writing a Wolfram Language Function
Writing a Wolfram Language Function
OPTIONS
Learning Objectives
Learning Objectives
Options
Options
Adding options to functions
Deal with duplicated options
Filter options into part of a function
Restrict option names and values
Summary
Summary
Options
Options
Options
Options
Adding Options
Adding Options
Adding options to a function provides a way to add extra functionality without cluttering the body of the function.
Generally, custom option names should be descriptive, UpperCamelCase strings. While functions like OptionValue often treat strings and symbols interchangeably, using strings avoids potential clashes with other symbols.
Built-in functions for managing options
Built-in functions for managing options
Guide: Options Management
Adding options to a function typically requires the use of three closely related functions: Options, OptionValue and OptionsPattern.
Options gives the list of default options assigned to a function:
Options[Plot]
OptionValue gives the value of a particular option:
OptionValue[Plot,AlignmentPoint]
OptionsPattern represents a collection of options given as a sequence or list of rules:
MatchQ[{"Option1"optionValue1,"Option2"->optionValue2},OptionsPattern[]]
Standard usage
Standard usage
Here is a typical setup using Options and OptionsPattern:
ClearAll[styleText];Options[styleText]={FontColor->Red,FontWeight->Bold};styleText[text_,options:OptionsPattern[]]:=Style[text,options];
A named pattern (options) has been used on the left-hand side to enable the options to be inserted anywhere on the right-hand side.
When the function is evaluated, the default options are not used unless they are listed explicitly:
styleText["text"]styleText["text",FontColor->Red]styleText["text",FontWeight->Bold]styleText["text",FontColor->Red,FontWeight->Bold]
You can, however, ensure that they are used from the get-go:
ClearAll[styleText];Options[styleText]={FontColor->Red,FontWeight->Bold};styleText[text_,options:OptionsPattern[]]:=Style[text,options,
Sequence@@Options[styleText]
];styleText["text"]styleText["text",FontColor->Blue,FontWeight->Plain]Rather than inserting all options in one place, you can pick and choose particular options to be used in different places. This is where OptionValue comes in:
ClearAll[styleText];Options[styleText]={FontColor->Red,FontWeight->Bold,"UpperCase"->False};styleText[string_,options:OptionsPattern[]]:=Style[If[TrueQ[
OptionValue["UpperCase"]
],ToUpperCase[string],string],options,FontColor->OptionValue[FontColor]
];styleText["text"]styleText["text",FontColor->Blue]styleText["text","UpperCase"->True](Note that the function name did not need to be specified inside each OptionValue, unlike the Plot example earlier.)
Option values can be delayed:
ClearAll[styleText];Options[styleText]={
FontColor:>RandomColor[]
};styleText[text_,options:OptionsPattern[]]:=Style[text,options,FontColor->OptionValue[FontColor]];styleText["text"](*Evaluatethismultipletimes*)
Mistaking options for arguments
Mistaking options for arguments
Without pattern restrictions, options may be misinterpreted as arguments.
Create a function that returns a styled word a number of times:
ClearAll[multiWord];Options[multiWord]={"Colour"->Red,"Weight"->Plain};multiWord[word_:"defaultWord",repetitions_:1,OptionsPattern[]]:=Style[StringJoin[ConstantArray[word,repetitions]],OptionValue["Colour"],OptionValue["Weight"]];
When only options are given, they are mistaken for arguments:
Adding pattern restrictions to the arguments fixes this issue:
Options
Options
Duplicated Options
Duplicated Options
In the case of duplicated options, only the first option value will be used.
Consider this definition of styleText from earlier, where the implicit options (options) are listed before the explicit options (Options[styleText]):
In this case, the function works as intended; adding new options changes the output:
However, if the order of the options is reversed, the explicit options take precedence instead:
To be absolutely sure which option values are being used in a function, it is good practice to remove any duplicates:
Options
Options
Filtering Options
Filtering Options
Filtering options with FilterRules is a way to ensure that all the right options go to all the right parts of a function, making it more robust.
No matter the order in which they are used, options will be filtered to the relevant parts of the function:
Options
Options
Restricting Options
Restricting Options
Another way to make a function more robust is to restrict the option names or values that can be used within it. This is typically done with Condition.
Option names
Option names
Often, option names are required to be a members of a pre-defined list.
Require all option names of a function to be members of (the keys of) the default list of options:
Option values
Option values
Like arguments, option values are often required to be of a particular form (string, integer, etc.).
Require the value of a function’s “Colour” option to be a valid colour:
Summary
Summary
In this part of the course, you have covered:
Implementing options
Duplicated options
Filtering options
Restricting options
Initialisation
Initialisation