Framework for options validation in Mathematica.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
OptionsValidation
buildScripts
.MathematicaResources
.gitignore
.project
BootstrapInstall.m
LICENSE
NoInstall.m
PacletInfo.m
README.md

README.md

OptionsValidation

releases SemVer 2.0.0 license MIT ![Mathematica 8.0 - 11.0](http://img.shields.io/badge/Mathematica-8.0 -- 11.0-brightgreen.svg)

Framework for options validation in Mathematica.

Description

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.

Installation

Automatic installation

To install OptionsValidation package evaluate:

Import["https://raw.githubusercontent.com/jkuczm/MathematicaOptionsValidation/master/BootstrapInstall.m"]

Note that this will also install ProjectInstaller package, if you don't have it already installed.

To load OptionsValidation package evaluate: Needs["OptionsValidation`"].

Manual installation

  1. Download latest released OptionsValidation.zip file.

  2. Extract downloaded OptionsValidation.zip to any directory which is on Mathematica $Path, e.g. to one obtained by evaluating FileNameJoin[{$UserBaseDirectory,"Applications"}].

  3. To load the package evaluate: Needs["OptionsValidation`"]

No installation

To use package directly from the Web, without installation, evaluate:

Import["https://raw.githubusercontent.com/jkuczm/MathematicaOptionsValidation/master/NoInstall.m"]

Compatibility

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 earlier (6.0+) versions of Mathematica.

Bugs and requests

If you find any bugs, or have a feature request, please create an issue on GitHub.

Contributing

Feel free to fork and send pull requests.

If you want to use Ant scripts from this repository you will also need to install WWBCommon project.

All contributions are welcome!

Usage in other packages

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.

License

This package is released under The MIT License.

Attribution

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.

Versioning

Releases of this package will be numbered using Semantic Versioning guidelines.