Version: 1.0

» Support Tools Such as This One! «

({{To help defray the cost of creating tools such as this, please click on the following link where other tools produced by Scientific Arts are posted}, {}, {MouseOver}, {}, {and click on the various Google Advertising links on the side of the page and those on other pages on the ScientificArts.com site.}, {}, {Thank You!}, {}, {Each such click will take you to the advertiser's page and will cause small advertising payments to be made by Google to Scientific Arts at no expense to you.}})

Explore A WorkLife FrameWork at MouseOver. 30 day trial version available.

FunctionsWithOption: Code

ClearAll[FunctionsWithOption,LoadContext,ExcludeGlobalContext,DeleteGlobalVersion,$FunctionsWithOptionVersion];

Version number

$FunctionsWithOptionVersion="1.0";

Usage Messages

LoadContext::usage="LoadContext is an option to FunctionsWithOption which specifies whether to load a supplied Context if it is not currently loaded. The default value is LoadContext->True. ";

ExcludeGlobalContext::usage="ExcludeGlobalContext is an option to FunctionsWithOption which specifies whether or not to exclude the Global` Context in its evaluation.  The default value is ExcludeGlobalContext->True.";

DeleteGlobalVersion::usage="DeleteGlobalVersion is an option to FunctionsWithOption which specifies that if the supplied option exists in the Global` Context or is created in the Global` Context through the execution of FunctionsWithOption, then its Global` version should be Removed. The default value is DeleteGlobalVersion->True. The Global` version will only be Removed if ExcludeGlobalContext->True. ";

$FunctionsWithOptionVersion::usage="$FunctionsWithOptionVersion gives the version of this implementation of FunctionsWithOption. ";

FunctionsWithOption::usage="FunctionsWithOption ";

Attributes

Attributes[FunctionsWithOption]={HoldAll};

Options

Options[FunctionsWithOption]={Grid->False,LoadContext->True,ExcludeGlobalContext->True,DeleteGlobalVersion->True,Frame->True,Alignment->Left};

Messages

FunctionsWithOption::nocont="The Context `1` is not one of the curretly loaded Contexts. Set the option LoadContext->True to automatically load the Context. ";

FunctionsWithOption::notcontext="The supplied Context `1` is not of the correct form ending with a \"`\". ";

FunctionsWithOption::value="The symbol that was supplied as the queried option, `1`, has a value. ";

Form 1: Specify a Context

A single Context:

FunctionsWithOption[option_Symbol,context_String,opts:OptionsPattern[]]:=

Catch@Module[{theOption,names,options,optionsData,grid,loadContext,contextLoaded,excludeGlobalContext,deleteGlobalVersion,removeGlobal},

{grid,loadContext,excludeGlobalContext,deleteGlobalVersion}={Grid,LoadContext,ExcludeGlobalContext,DeleteGlobalVersion}/.Flatten[{opts,Options[FunctionsWithOption]}];


removeGlobal=Function[x,
Quiet@If[excludeGlobalContext&&deleteGlobalVersion,
Remove[#]&["Global`"<>ToString[Unevaluated[x]]]],
{HoldAll}];


If[!(StringMatchQ[context, "*`"]),
Throw[Message[FunctionsWithOption::notcontext,context];
removeGlobal[option];
{}]];

If[excludeGlobalContext&&(context==="Global`"),
Throw[
removeGlobal[option];
{}]];


If[ValueQ[#]&[Unevaluated[option]],Throw[Message[FunctionsWithOption::value,ToString@Unevaluated[option]];
removeGlobal[option];
{}]];

theOption=ToString[option];


If[Context[option]==="Global`"&&excludeGlobalContext&&deleteGlobalVersion,Quiet@Remove[option]];


Switch[loadContext,
True,
(contextLoaded=Needs[context];
If[contextLoaded===$Failed,
Throw[
removeGlobal[option];
{}]]),

_,
If[!MemberQ[Contexts[],context],
Throw[Message[FunctionsWithOption::nocont,context];
removeGlobal[option];
{}]]
];

theOption=ToExpression[theOption];

names=Flatten[Names[context<>"*"]];

options=Quiet[Options[ToExpression[Unevaluated[#]]]&/@names];

optionsData=Transpose[{names,options}];

optionsData=Cases[optionsData,{w_String,{___,z:((theOption->_)|(theOption:>_)),___}}:>{w,z}];

removeGlobal[option];

Switch[grid,

True,
Grid[optionsData,FilterRules[Flatten[{opts,Options[FunctionsWithOption]}],Options[Grid]]],

_,
optionsData
]

];

Multiple Contexts in a list:

FunctionsWithOption[option_Symbol,contexts:{__String},opts:OptionsPattern[]]:=
Module[{optionsData,grid,theContexts},

{grid}={Grid}/.Flatten[{opts,Options[FunctionsWithOption]}];

theContexts=Union[contexts];

optionsData=FunctionsWithOption[option,#,Grid->False,opts]&/@theContexts;

optionsData=Flatten[optionsData,1];

Switch[grid,

True,
Grid[optionsData,FilterRules[Flatten[{opts,Options[FunctionsWithOption]}],Options[Grid]]],

_,
optionsData
]

];

Form 2:  Specify a symbol

From the symbol the Context is obtained and all symbols in that Context with the given option are returned

A single symbol:

FunctionsWithOption[option_Symbol,packageSymbol_Symbol,opts:OptionsPattern[]]:=
Module[{context},

context=Context[packageSymbol];
FunctionsWithOption[option,#,opts]&[context]

];

Multiple symbols:

FunctionsWithOption[option_Symbol,packageSymbols:{__Symbol},opts:OptionsPattern[]]:=
Module[{contexts},

contexts=Union[Context/@(Unevaluated@packageSymbols)];

FunctionsWithOption[option,#,opts]&[contexts]

];

Form 3: Fall-through for a single argument

The supplied symbol is queried only in its own Context:

FunctionsWithOption[option_Symbol,opts:OptionsPattern[]]:=FunctionsWithOption[option,option,opts]

Documentation

Purpose

FunctionsWithOption is a simple tool that allows you to find functions that have a particular option.  In a way it is an inverse of Mathematica's Options function.  Whereas the function Options will give you a list of all of the options for a particular function, e.g.:

Options[FindRoot]

FunctionsWithOption will give you all the functions that have a particular option

FunctionsWithOption[AccuracyGoal]

The form of this output is a list of pairs.  The first item in each pair is the function

Various forms of use: Single argument form

Single argument form

FunctionsWithOption takes on several different argument sets.  The first is the simplest.  This is a single argument with the option that you are interested in as in the preceding example.  Here is another example:

FunctionsWithOption[TaggingRules]

Note that, in this form, FunctionsWithOption looks for all of those functions that have the queried option in the Context of that option.  It will not return any results for other Contexts that have functions that use that option.   So, in the above example FunctionsWithOption is looking for all of the functions that have the TaggingRules option in the System` Context because

Context[TaggingRules]

Care with the Global` Context

Note also that if  the single argument form FunctionsWithOption is called with a symbol from a Context that hasn't yet been loaded, then that symbol will be placed in the Global` Context.  This may not be quite what you want.  There is an option to FunctionsWithOption, DeleteGlobalVersion, which if set as DeleteGlobalVersion->True (the default setting), causes any symbol that is introduced into the Global` Context through the execution of FunctionsWithOption, to be removed.

Here is an example.

First make sure that there is no current symbol called testSymbol

Remove[testSymbol]

Names["testSymbol"]

Now execute FunctionsWithOption with DeleteGlobalVersion->True:

FunctionsWithOption[testSymbol,DeleteGlobalVersion->True]

The symbol still is not in the Global` context:

Names["testSymbol"]

It we had executed this with DeleteGlobalVersion->True then testSymbol would remain in the Global` Context after execution:

FunctionsWithOption[testSymbol,DeleteGlobalVersion->False]

Names["testSymbol"]

To clean things up for this example Remove testSymbol:

Remove[testSymbol]

Two argument forms

There are several two argument forms for FunctionsWithOption.  In all cases the first argument is the symbol that you are querying.

Symbol and Context

For this case the second argument is the Context that you are looking in.  If that Context has not yet been loaded then FunctionsWithOption will load it before looking for the functions in that context that have the queried option.  Only those functions in the Context that have the symbol as an option will be returned: all other contexts will be ignored.   Here is an example for the Combinatorica package. Combinatorica is not loaded by default when Mathematica is first started, but this command will load it.  In this example we are using the option Grid->True to show a formatted output:

FunctionsWithOption[EdgeStyle,"Combinatorica`",Grid->True]

Even though the symbol Method is defined in the System` context, it is used in some Combinatorica functions:

FunctionsWithOption[Method,"Combinatorica`",Grid->True]

Symbol and a list of Contexts

The second argument of FunctionsWithOption can also be a list of Contexts.  In this case FunctionsWithOption returns all of the functions from each of the contexts that have the option.

Here are the functions in the System` Context that have the option Initialization:

FunctionsWithOption[Initialization,"System`",Grid->True]

Here are the functions in the Combinatorica` Context that have the option Initialization:

FunctionsWithOption[Initialization,"Combinatorica`",Grid->True]

And here are the functions in both the System` and Combinatorica` context that have the Initialization option:

FunctionsWithOption[Initialization,{"Combinatorica`","System`"},Grid->True]

A warning:

You might be tempted to execute something like (the following cell is not an executable cell so that you do not accidentally execute it):

FunctionsWithOption[Initialization, Contexts[]]

Note however that this may cause Mathematica to attempt to initialize many of its data paclets which, in addition to possibly taking a very long time, may also cause a large amount of data to be written to your disk.

Symbol and a symbol

The final form is where the second argument for FunctionsWithOption is a symbol.  In this case all of the functions from the context of the second argument are returned that have the first argument as an Option.

AnimateGraph is a function in the Combinatorica package:

FunctionsWithOption[Initialization,AnimateGraph,Grid->True]

Plot is a function in the System` Context:

FunctionsWithOption[Initialization,Plot,Grid->True]

Note that if the Context of the symbol in second argument has not been loaded when FunctionsWithOption is executed then that symbol will be placed in the Global` Context.  In this case you are not likely to get the results you were expecting.

Symbol and a list of symbols

As in case of explicitly supplying a list of contexts, the second argument for FunctionsWithOption can take a list of symbols.  In this case all of the functions from the set of Contexts for theses symbols that have the option are returned.  Here Plot is in the System` context and NecklacePolynomial is in the Combinatorica` context:

FunctionsWithOption[Initialization,{Plot,NecklacePolynomial},Grid->True]

Options

FunctionsWithOption takes several options:

Options[FunctionsWithOption]

The option Grid determines whether the result form FunctionsWithOption is returned in a formatted grid.  We showed several examples of this above.

Here are the usage messages for the options LoadContext, ExcluedGlobalContext, and DeleteGlobal:

?LoadContext

?ExcludeGlobalContext

?DeleteGlobalVersion

The remaining explicit options to FunctionsWithOption—Frame and Alignment—are used when Grid->True to format the gridded output. But FunctionsWithOption can also take on any other of the options to Grid as in the following:

FunctionsWithOption[Initialization,Plot,Grid->True, Alignment->{Right,Left},Frame->All,Background->{{None,Lighter@Lighter@Gray},None}]

License

A license for use of this Mathematica code, Package, or tool (the "Product") is provided free of charge from MouseOver for non-commercial use only.  For license information or any other use MouseOver directly.

You may redistribute this code to others, but may only do so by also including this notebook and must also include this copyright license information in all other uses.

Ccpyright, © 2009, Scientific Arts, LLC. Scientific Arts is the sole holder of the copyright to this Product. 

This Mathematica Package, Code, or Tool is provided as is, with no waranty whatsoever.  

IN NO EVENT SHALL SCIENTIFIC ARTS, LLC BE LIABLE FOR ANY LOST PROFITS, LOST BENEFITS, OR ANY CONSEQUENTIAL, INDIRECT, INCIDENTAL, SPECIAL, OR PUNITIVE DAMAGES, WHETHER IN CONTRACT, TORT, OR OTHERWISE, EVEN IF LICENSOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. LICENSOR'S JOINT CUMULATIVE LIABILITY TO YOU OR ANY OTHER PARTY FOR ANY LOSS OR DAMAGES RESULTING FROM ANY CLAIMS, DEMANDS, ACTIONS, OR OTHERWISE ARISING OUT OF OR RELATING TO THIS AGREEMENT SHALL NOT EXCEED THE LICENSE FEE PAID FOR THE PRODUCT.

Scientific Arts, LLC is not affiliated with Wolfram Research Inc.
Mathematica is a registered trademark of WolframResearch, Inc.

Null