jkuczm / mathematicaoptionsvalidation

Framework for options validation in Mathematica.

OptionsValidation

Framework for options validation in Mathematica.

• Description
• Installation
  • Automatic installation
  • Manual installation
  • No installation
• Compatibility
• Bugs and requests
• Contributing
• Usage in other packages
• License
• Versioning

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 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"

Manual installation

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"

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 older (6.0+) and newer (11.1+) versions of Mathematica, but it was not tested with these versions.

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.

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.

mathematicaoptionsvalidation's Issues

PacletInfo needs Context

If a paclet is installed via PacletInstall it needs a "Kernel" extension with a "Context" spec to load properly it seems (just tried to load the installed paclet). Try changing the Extensions to:

Extensions -> 
        {
            {"Kernel", "Context"->{"OptionsValidation`"}},
            {"Documentation", Language -> "English"}
        }

and then it should work fine.

Paclet Server Integration

I was wondering if you'd want to add your package to the Paclet Server / Package Repo I've set up for the general Mathematica community. Per this I'm trying to increase awareness and get more paclets on the server so that more people can benefit from it.

I can handle any initial reformatting necessary to make everything work right, and I'll submit a pull request with any changes.