​
Slide
1
of
9

Writing a Wolfram Language Function

OPTIONS
​
​
Slide
2
of
9

Learning Objectives

Options


  • Adding options to functions
  • 
  • Deal with duplicated options
  • 
  • Filter options into part of a function
  • 
  • Restrict option names and values
  • Summary

    ​
    ​
    Slide
    3
    of
    9

    Options

    ​
    Slide
    4
    of
    9

    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

    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

    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]
    (Apply[Sequence, …] has been used here to replace the List head with Sequence.)
    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

    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:
    ​
    Slide
    5
    of
    9

    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:
    ​
    Slide
    6
    of
    9

    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.
    Create a function that takes a Graphics option as well as a custom title option:
    No matter the order in which they are used, options will be filtered to the relevant parts of the function:
    ​
    Slide
    7
    of
    9

    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

    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

    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:
    Note that the default value for Lookup here (Black) won’t ever get called. It is used to ensure that ColorQ evaluates to True in the case of no options being provided.
    ​
    Slide
    8
    of
    9

    Summary

    In this part of the course, you have covered:
    
  • Implementing options
  • 
  • Duplicated options
  • 
  • Filtering options
  • 
  • Restricting options
  • ​
    Slide
    9
    of
    9

    Initialisation