A Haskell-land wrapper around the name of a configuration option. Developers are encouraged to define and use ConfigOption values to avoid two classes of errors: typos in configuration option names; and dynamic type-cast failures. Both classes of errors can be lifted to statically-checkable failures (missing symbols and type-checking, respectively) by consistently using ConfigOption values.

The following example indicates the suggested usage

  asdfFrob :: ConfigOption BaseRealType
  asdfFrob = configOption BaseRealRepr "asdf.frob"

  asdfMaxBound :: ConfigOption BaseIntegerType
  asdfMaxBound = configOption BaseIntegerRepr "asdf.max_bound"

Construct a ConfigOption from a string name. Idiomatic usage is to define a single top-level ConfigOption value in the module where the option is defined to consistently fix its name and type for all subsequent uses.

Retrieve the run-time type representation of tp.

Reconstruct the original string name of this option.

Reconstruct the original string name of this option.

Get the individual dot-separated segments of an option's name.

An OptionSetting gives the direct ability to query or set the current value of an option. The getOption field is an action that, when executed, fetches the current value of the option, if it is set. The setOption method attempts to set the value of the option. If the associated opt_onset validation method rejects the option, it will retain its previous value; otherwise it will be set to the given value. In either case, the generated OptionSetResult will be returned.

A utility class for making working with option settings easier. The tp argument is a BaseType, and the a argument is an associcated Haskell type.

Given a unicode text value, set the named option to that value or generate an OptSetFailure exception if the option is not a unicode text valued option.

Given an integer value, set the named option to that value or generate an OptSetFailure exception if the option is not an integer valued option.

Given a boolean value, set the named option to that value or generate an OptSetFailure exception if the option is not a boolean valued option.

An option defines some metadata about how a configuration option behaves. It contains a base type representation, which defines the runtime type that is expected for setting and querying this option at runtime.

Update the opt_default_value field.

Update the opt_onset field.

When setting the value of an option, a validation function is called (as defined by the associated OptionStyle). The result of the validation function is an OptionSetResult. If the option value given is invalid for some reason, an error should be returned. Additionally, warning messages may be returned, which will be passed through to the eventual call site attempting to alter the option setting.

Accept the new option value with no errors or warnings.

Accept the given option value, but report a warning message.

Reject the new option value with an error message.

Throw an exception if the given OptionSetResult indicates an error. Otherwise, return any generated warnings.

An inclusive or exclusive bound.

Standard option style for boolean-valued configuration options

Standard option style for integral-valued configuration options

Standard option style for real-valued configuration options

Option style for real-valued options with upper and lower bounds

Option style for real-valued options with a lower bound

Option style for real-valued options with an upper bound

Option style for integer-valued options with upper and lower bounds

Option style for integer-valued options with a lower bound

Option style for integer-valued options with an upper bound

A configuration style for options that must be one of a fixed set of text values

A configuration syle for options that must be one of a fixed set of text values. Associated with each string is a validation/callback action that will be run whenever the named string option is selected.

A configuration style for options that are expected to be paths to an executable image. Configuration options with this style generate a warning message if set to a value that cannot be resolved to an absolute path to an executable file in the current OS environment.

A ConfigDesc describes a configuration option before it is installed into a Config object. It consists of a ConfigOption name for the option, an OptionStyle describing the sort of option it is, and an optional help message describing the semantics of this option.

The most general method for constructing a normal ConfigDesc.

Construct an option using a default style with a given initial value

Construct an option using a default style with a given initial value. Also provide a validation function to check new values as they are set.

Construct an option using a default style with no initial value.

Construct an option using a default style with no initial value. Also provide a validation function to check new values as they are set.

The copyOpt creates a duplicate ConfigDesc under a different name. This is typically used to taking a common operation and modify the prefix to apply it to a more specialized role (e.g. solver.strict_parsing --> solver.z3.strict_parsing). The style and help text of the input ConfigDesc are preserved, but any deprecation is discarded.

Used as a wrapper for an option that has been deprecated. If the option is actually set (as opposed to just using the default value) then this will emit an OptionSetResult warning that time, optionally mentioning the replacement option (if specified).

There are three cases of deprecation: 1. Removing an option that no longer applies 2. Changing the name or heirarchical position of an option. 3. #2 and also changing the type. 4. Replacing an option by multiple new options (e.g. split url option into hostname and port options)

In the case of #1, the option will presumably be ignored by the code and the warnings are provided to allow the user to clean the option from their configurations.

In the case of #2, the old option and the new option will share the same value storage: changes to one can be seen via the other and vice versa. The code can be switched over to reference the new option entirely, and user configurations setting the old option will still work until they have been updated and the definition of the old option is removed entirely.

NOTE: in order to support #2, the newer option should be declared (via insertOption) *before* the option it deprecates.

In the case of #3, it is not possible to share storage space, so during the deprecation period, the code using the option config value must check both locations and decide which value to utilize.

Case #4 is an enhanced form of #3 and #2, and is generally treated as #3, but adds the consideration that deprecation warnings will need to advise about multiple new options. The inverse of #4 (multiple options being combined to a single newer option) is just treated as separate deprecations.

NOTE: in order to support #4, the newer options should all be declared (via insertOption) *before* the options they deprecate.

Nested deprecations are valid, and replacement warnings are automatically transitive to the newest options.

Any user-supplied value for the old option will result in warnings emitted to the OptionSetResult for all four cases. Code should ensure that these warnings are appropriately communicated to the user to allow configuration updates to occur.

Note that for #1 and #2, the overhead burden of continuing to define the deprecated option is very small, so actual removal of the older config can be delayed indefinitely.

The main configuration datatype. It consists of a Read/Write var containing the actual configuration data.

Construct a new configuration from the given configuration descriptions.

Extend an existing configuration with new options. An OptCreateFailure exception will be raised if any of the given options clash with options that already exists.

Extend an existing configuration with new options. If any of the given options are already present in the configuration, nothing is done for that option and it is silently skipped.

Create a new configuration object that shares the option settings currently in the given input config. However, any options added to either configuration using extendConfig will not be propagated to the other.

Option settings that already exist in the input configuration will be shared between both; changes to those options will be visible in both configurations.

Given a ConfigOption name, produce an OptionSetting object for accessing and setting the value of that option.

An exception is thrown if the named option cannot be found the Config object, or if a type mismatch occurs.

Given a text name, produce an OptionSetting object for accessing and setting the value of that option.

An exception is thrown if the named option cannot be found.

A ConfigValue bundles together the name of an option with its current value.

Given the name of a subtree, return all the currently-set configuration values in that subtree.

If the subtree name is empty, the entire tree will be traversed.

Given the name of a subtree, compute help text for all the options available in that subtree.

If the subtree name is empty, the entire tree will be traversed.

Verbosity of the simulator. This option controls how much informational and debugging output is generated. 0 yields low information output; 5 is extremely chatty.

Return an operation that will consult the current value of the verbosity option, and will print a string to the given Handle if the provided int is smaller than the current verbosity setting.