Framework for options validation in Mathematica.
- Description
- Installation
- Compatibility
- Bugs and requests
- Contributing
- Usage in other packages
- License
- Versioning
This package provides a framework simplifying validation of options.
It provides functions registering arbitrary tests for values of options, of given symbols, with names matching given patterns. Test of relations between different options can be also registered.
Registered tests can be automatically used in various different strategies
of option value testing. Tests can be performed while evaluating body of
function when option values are accessed, or they can be performed upfront
while matching function pattern.
When tests fail - function can either return a value denoting failure
(e.g. $Failed), or can remain unevaluated.
Default values of options can be also automatically validated when they are changed.
You can find basic usage examples in OptionsValidation PackageData entry. More involved examples can be found in answers to Manipulations with options and How to check the validity of an option value questions on Mathematica Stack Exchange.
To install newest version of OptionsValidation package, directly from repository, in Mathematica version 10 or newer, evaluate following code:
PacletInstall@"http://github.com/jkuczm/MathematicaOptionsValidation/releases/download/v0.1.1/OptionsValidation-0.1.1.paclet"Note that above requires allowing Mathematica to use the Internet.
To load OptionsValidation package evaluate:
Needs@"OptionsValidation`"To uninstall OptionsValidation package evaluate:
PacletUninstall@"OptionsValidation"If in your setup Mathematica doesn't have Internet access,
or you're using version older than 10, download
OptionsValidation.0.1.1.paclet
file and evaluate PacletInstall with path to downloaded file:
PacletInstall@"path/to/downloaded/OptionsValidation.0.1.1.paclet"To load OptionsValidation package evaluate:
Needs@"OptionsValidation`"To uninstall OptionsValidation package evaluate:
PacletUninstall@"OptionsValidation"To use package directly from the Web, without installation, evaluate:
Import@"https://raw.githubusercontent.com/jkuczm/MathematicaOptionsValidation/master/NoInstall.m"This package contains extensive automatic test suite. Package is tested with all Mathematica major and minor versions from 8.0 to 11.0 on Linux. Since it doesn't contain any OS specific code it should work with above versions on all operating systems.
There's also no obvious reason for package not to work on older (6.0+) and newer (11.1+) versions of Mathematica, but it was not tested with these versions.
If you find any bugs, or have a feature request, please create an issue on GitHub.
Feel free to fork and send pull requests.
All contributions are welcome!
There are two ways to use OptionsValidation with your own package.
First is to require users, of your package, to install OptionsValidation
separately. Your package can then load it, as any other external package, using
Get["OptionsValidation`"]. Be aware that if your package requires specific
version of OptionsValidation and user wants to use other package requiring
different version of OptionsValidation it may lead to a version conflict.
Second way is to include specific version of OptionsValidation as sub-package
of your package. To do it, simply put OptionsValidation.m file inside main
directory of your package. And load it using Get["`OptionsValidation`"]
(note the grave accent character at the beginning of string) somewhere inside
main context of your package.
Directory structure of YourPackage` can, for example, look like this:
YourPackage
├── Kernel
│ └── init.m
├── OptionsValidation.m
└── YourPackage.m
and YourPackage.m file:
BeginPackage["YourPackage`"]
(* Public symbols usage *)
Get["`OptionsValidation`"]
Begin["`Private`"]
(* Implementation *)
End[]
EndPackage[]This way specific version of OptionsValidation package, distributed with your
package, will be loaded as YourPackage`OptionsValidation` , and will be
completely independent of other versions of OptionsValidation possibly used by
user of your package.
This package is released under The MIT License.
WithOptionValueChecks and CheckedOptionValue functions are a derivative of
OptionCheck function
written by
Leonid Shifrin
used under
Creative Commons Attribution-ShareAlike 3.0 Unported License.
Idea for 2 argument "operator form" of CheckOption function was inspired by:
test function written
by Mr.Wizard
used under
Creative Commons Attribution-ShareAlike 3.0 Unported License.
Idea to allow loading package as a sub-package was inspired by system used in LTemplate package written by Szabolcs Horvát used under The MIT License.
Releases of this package will be numbered using Semantic Versioning guidelines.