ecl-logo Documentation

DefineOptions

DefineOptions[function,Options:>ops,SharedOptions:>sharedOps]⟹Null

sets the Options for function and saves metadata about the options for later usage.

Details

  • The order of input rules does not matter.
  • Only one of Options/SharedOptions is required.
    • Input
    Messages
  • AllowNullPatternAllowNull's value `1` must match BooleanP. Please change AllowNull's value.
    BadPatternOptions for `1` marked as IndexMatching, or to which other options IndexMatch, must use a single call to ListableP to define their pattern. Check `2`
    CategoryPatternCategory's value `1` must match _String. Please change Category's value.
    DescriptionPatternDescription's value `1` must match _String. Please change Description's value.
    DuplicateUnable to define options for `1`. Multiple options defined with the same names: `2`.
    FormatUnable to define options for `1`. Invalid options format.
    InvalidKey`2` are not valid keys for DefineOptions. You may only use Options or SharedOptions.
    InvalidKeysThe following keys were used in an list of rules to define an option and are invalid `1`. Only {OptionName,Default,AllowNull,Description,ResolutionDescription,Category,IndexMatchingInput,IndexMatching,Expandable,Pattern,SingletonPattern,Widget,Pooled} are valid keys. Please remove these invalid keys.
    InvalidWidgetA widget `1` was specified that does not pass ValidWidgetQ. Please reformat this widget so that it is valid.
    MissingOptionsFailure to copy options from `2` to `3`. Make sure `1` exist as options for `2` when defining options for `3`.
    MissingRequiredKeysThe following keys, `1`, are required to define an option but are missing. Please include these required keys in the options definition `2`.
    NoOptionsFailure to copy options from `1` to `2`. No options found for `1` when defining options for `2`.
    OptionNamePatternOptionName's value `1` must match _Symbol. Please change OptionName's value.
    PatternXorWidgetOne and only one of the keys {Pattern, Widget} can be used to define an option. Please add/remove these keys to satisfy
    PooledPatternPooled's value `1` must match BooleanP. Please change Pooled's value.
    SystemSymbolCannot define options for Mathematica symbol `1`.
    UnableToFindPrimitiveHeadUnable to find option information about the primitive, `1`, from the primitive set, `2`. Please make sure that DefinePrimitiveSet[...] was called on this primitive set.
    XorIndexMatchingInputAndParentExactly one of IndexMatchingInput and IndexMatchingParent must be set for each IndexMatching block in the options. Please include only one of these keys in order to define a valid index matching options block.

Examples

Basic Examples  (4)

Set Options (using the legacy syntax):

Set Options (using the new syntax):

Set SharedOptions, which are copied from other functions:

Set all types of options:

Additional Examples  (11)

Use two separate IndexMatching[...] blocks:

Options override SharedOptions:

Set all types of options:

Use option set in line with other options:

Use multiple option sets:

Option set can be overwritten by explicity listed options:

Explicitly defined options always take precedence over option sets. Option sets take precedence over shared options. After than any duplicated options from option sets or shared options are deleted (no duplicates are allowed in explictly defined options):

Define options as index-matching to inputs:

Protected symbols are unprotected and re-protected:

Unprotected symbols stay unprotected:

Options defined for the symbol take precedence over shared options:

Messages  (17)

AllowNullPattern  (1)

AllowNull must match BooleanP:

BadPattern  (2)

Print a message and returns $Failed if an IndexMatching option does not use ListableP to define its pattern:

Print a message and returns $Failed if the option to which an option is Index-Matched does not use ListableP to define its pattern:

CategoryPattern  (1)

Category must match _String:

DescriptionPattern  (1)

Description must match _String:

Duplicate  (1)

Throws a message and does not define options if the same option name is used twice:

Format  (1)

Invalid options format:

InvalidKey  (1)

Valid Options keys are Options and SharedOptions:

InvalidKeys  (1)

If an illegal key is specified, returns $Failed:

InvalidWidget  (1)

The provided widgets must be valid:

MissingOptions  (1)

Cannot share an option that does not exist for sharing function:

MissingRequiredKeys  (1)

If a required key is missing, returns $Failed. In this test, we are missing the OptionName key:

NoOptions  (1)

Cannot share options if they have not yet been defined for sharing function:

OptionNamePattern  (1)

The OptionName must be provided as a _Symbol:

PatternXorWidget  (1)

Only the Pattern or the Widget key can be provided:

SystemSymbol  (1)

Cannot define options for Mathematica symbols:

XorIndexMatchingInputAndParent  (1)

Exactly one of IndexMatchingInput and IndexMatchingParent must be set for each IndexMatching block in the options:

EMERALD CLOUD LAB
15500 Wells Port Drive
Austin, TX 78728
© 2023 Emerald Cloud Lab, Inc.