In a Sulfur plug-in, options are represented by objects, each of which is an instance of the Option class found in the Sulfur.Options module. An Option object only holds the description of an option; its current value is held elsewhere, inside the plug-in object.
Normally, you won't use the Option class directly. Each option type is represented by a subclass of Option, named predictably Boolean, String, and so forth. All of these classes accept the same parameters at object creation; the general form of the call used to create an object is as follows:
Type(name, default, title, description, flags, cmd_names, ...)
Only the name parameter is required; the rest will be filled in with appropriately null values if not supplied. The parameters are used as follows:
The canonical name of the option. This is the name that must be used to access the option's value, and the name it will be matched to when reading configuration files.
The default value of this option. The value should be of a type appropriate to the option; for example, if the option is a String, Integer, or Float it should be a value of the corresponding Python type.
A one-line title or description of the option.
A description of the option, which can be of any length and include multiple lines and paragraphs.
Either None (for no flags), or a tuple containing one or more of the following flags. (The flag names given below are in the Sulfur.Options module.)
Load this option's value from if it is found in a configuration file, but don't save it to any configuration file if it is changed.
Don't load this option's value from any configuration file, and don't save it either.
Don't allow this option to be configured interactively.
Don't allow this option's value to be specified on the command line.
A list of names by which this option can be set from the command line. If it is None (the default), the option's canonical name will be used, but if this parameter is a list of strings, then all of the listed names will be used instead of the option's canonical name.
For instance, if the option's canonical name is debug and cmd_names is None, then it will be accessible from the command line as --debug. If, however, cmd_names is ['d','dbg'], then the option will be accessible from the command line as -d and --dbg, but not as --debug!
The reason for this behavior is that sometimes the best name for an option inside a program is not the most logical way to refer to it on the command line.
Most option types accept additional parameters, usually to set validation limits. See the descriptions below for more detail.
Each Option object has the following methods:
Returns true if the specified flag is set.
Tests whether the specified value is a valid one for this option. If the value is of the wrong Python type or is invalid for some other reason, a ValidationError exception will be raised. The return value of this method doesn't matter; if no exception is raised, the value passed is valid.
Converts the given string to an appropriate value for this option, and returns it. If the resulting value is invalid, a ValidationError exception will be raised; if the string cannot be converted at all, other exceptions might arise as well.
Normally, you won't need to call an option's methods directly, since the standard plug-in methods set_option, get_option, and configure do it for you.