settings.pl -- Setting management

This library allows management of configuration settings for Prolog applications. Applications define settings in one or multiple files using the directive setting/4 as illustrated below:

:- use_module(library(settings)).

:- setting(version, atom,   '1.0', 'Current version').
:- setting(timeout, number,    20, 'Timeout in seconds').

The directive is subject to term_expansion/2, which guarantees proper synchronisation of the database if source-files are reloaded. This implies it is not possible to call setting/4 as a predicate.

Settings are local to a module. This implies they are defined in a two-level namespace. Managing settings per module greatly simplifies assembling large applications from multiple modules that configuration through settings. This settings management library ensures proper access, loading and saving of settings.

author: - Jan Wielemaker
See also: - library(config) distributed with XPCE provides an alternative aimed at graphical applications.

setting(:Name, +Type, +Default, +Comment) is det

Define a setting. Name denotes the name of the setting, Type its type. Default is the value before it is modified. Default can refer to environment variables and can use arithmetic expressions as defined by eval_default/4.

If a second declaration for a setting is encountered, it is ignored if Type and Default are the same. Otherwise a permission_error is raised.

Arguments:

`Name`	- `Name` of the setting (an atom)
`Type`	- `Type` for setting. One of `any` or a type defined by must_be/2.
`Default`	- `Default` value for the setting.
`Comment`	- Atom containing a (short) descriptive note.

setting(:Name, ?Value) is nondet

True when Name is a currently defined setting with Value. Note that setting(Name, Value) only enumerates the settings of the current module. All settings can be enumerated using setting(Module:Name, Value). This predicate is det if Name is ground.

Errors: - existence_error(setting, Name)

clear_setting_cache is det[private]

Clear the cache for evaluation of default values.

eval_default(+Default, +Module, +Type, -Value) is det[private]

Convert the settings default value. The notation allows for some `function-style' notations to make the library more generic:

env(Name): Get value from the given environment variable. The value is handed to convert_setting_text/3 to convert the textual representation into a Prolog term. Raises an existence_error of the variable is not defined.
env(Name, Default): As env(Name), but uses the value Default if the variable is not defined.
setting(Name): Ask the value of another setting.
Expression: If Type is numeric, evaluate the expression. env(Var) evaluates to the value of an environment variable. If Type is atom, concatenate A+B+.... Elements of the expression can be env(Name).

eval_list_default(+List, +Module, +ElementType, -DefaultList)[private]

Evaluate the default for a list of values.

expr_to_list(+Expression, +Module)// is det[private]

Process the components to create an atom. Atom concatenation is expressed as A+B. Components may refer to envrionment variables.

env(+Name:atom, -Value:number) is det

env(+Name:atom, +Default:number, -Value:number) is det

Evaluate environment variables on behalf of arithmetic expressions.

numeric_type(+Type, -BaseType)[private]

True if Type is a numeric type and BaseType is the associated basic Prolog type. BaseType is one of integer, float or number.

set_setting(:Name, +Value) is det

Change a setting. Performs existence and type-checking for the setting. If the effective value of the setting is changed it broadcasts the event below.

settings(changed(Module:Name, Old, New))

Note that modified settings are not automatically persistent. The application should call save_settings/0 to persist the changes.

Errors: - existence_error(setting, Name); - type_error(Type, Value)

restore_setting(:Name) is det

Restore the value of setting Name to its default. Broadcast a change like set_setting/2 if the current value is not the default.

set_setting_default(:Name, +Default) is det

Change the default for a setting. The effect is the same as set_setting/2, but the new value is considered the default when saving and restoring a setting. It is intended to change application defaults in a particular context.

check_type(+Type, +Term)[private]

Type checking for settings. Currently simply forwarded to must_be/2.

load_settings(File) is det

load_settings(File, +Options) is det

Load local settings from File. Succeeds if File does not exist, setting the default save-file to File. Options are:

undefined(+Action): Define how to handle settings that are not defined. When error, an error is printed and the setting is ignored. when load, the setting is loaded anyway, waiting for a definition.

If possibly changed settings need to be persistent, the application must call save_settings/0 as part of its shutdown. In simple cases calling at_halt(save_settings) is sufficient.

store_setting(Term, +Options)[private]

Store setting loaded from file in the Prolog database.

save_settings is semidet

save_settings(+File) is semidet

Save modified settings to File. Fails silently if the settings file cannot be written. The save_settings/0 only attempts to save the settings file if some setting was modified using set_setting/2.

Errors: - context_error(settings, no_default_file) for save_settings/0 if no default location is known.

current_setting(?Setting) is nondet

True if Setting is a currently defined setting

setting_property(+Setting, +Property) is det

setting_property(?Setting, ?Property) is nondet

Query currently defined settings. Property is one of

comment(-Atom)
type(-Type): Type of the setting.
default(-Default): Default value. If this is an expression, it is evaluated.
source((-File:-Line)): Location where the setting is defined.

list_settings is det

list_settings(+Module) is det

List settings to current_output. The second form only lists settings on the matching module.

To be done: - Compute the required column widths

convert_setting_text(+Type, +Text, -Value)

Converts from textual form to Prolog Value. Used to convert values obtained from the environment. Public to provide support in user-interfaces to this library.

Errors: - type_error(Type, Value)

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

list_settings(Arg1)
save_settings(Arg1)
load_settings(Arg1, Arg2)