Next: Configuration parameters, Up: Configuration functions [Contents][Index]
A configuration parameter is always evaluated within a configuration context. Each context is associated with a configuration file (although the file does not necessarily need to exist).
Each configuration context may have a parent context. If, when looking up a parameter, it has no value set in the selected context, the parent context is checked, and so on.
Several special contexts are always automatically defined: the default context, the system context, the user context and the cache context. The user context is the default parent context for all other configuration contexts, including newly-created ones.
Normally, you shouldn’t create a configuration context directly; you should obtain the configuration context associated with a path.
path-config-context looks for a configuration file named
lepton.conf. If path is not a directory, it is truncated,
and then a file named lepton.conf is looked for in that
directory. If none is found, the parent directory is checked, and so
on until a configuration file is found or the filesystem root is
reached. If no configuration file was found, the returned context
will be associated with a lepton.conf in the same directory as
path.
Warning: Do not assume that the configuration file associated
with the context returned by path-config-context is located in
the directory specified by path.
The default context is not associated with any physical path or on-disk configuration file, and has no parent context. It contains the default configuration used when no configuration file can be loaded.
Note: Normally, the default context should be populated with
built-in default configuration settings on start-up, before loading
any further configuration files. This approach is strongly
recommended, because it means that configuration parameters can then
be safely read without having to use config-has-group? and
config-has-key? to check if they are set (see Configuration groups and keys).
Since 1.10.
The system context is used for system-wide configuration. Its parent
context is the default context. It is located by searching
sys-config-dirs for a
${prefix}/share/lepton-eda/lepton-system.conf file.
Since 1.10.
The user context is used for user-specific configuration, and is
loaded from lepton-user.conf in user-config-dir.
Its parent context is the system context.
Since 1.10.
The cache context is used to store program-specific settings,
like dialog geometry and command history.
It has no parent configuration context.
The associated file is gui.conf
in $XDG_CACHE_HOME/lepton-eda/ directory (usually,
~/.cache/lepton-eda/).
That path can be determined by calling user-cache-dir
function from the (lepton os) module.
Returns the context associated with a configuration file given by path. It can be assigned a parent context parent (by default it has no parent context). The context is considered untrusted, unless the trusted parameter is set to ‘#t’.
Returns ‘#t’ if and only if cfg is a configuration context object.
Other than the default context, all configuration contexts are associated with an on-disk configuration file.
Return the filename of the configuration file associated with the context cfg. For some contexts (including the default context), this will return ‘#f’.
Since 1.10.
Attempt to load configuration parameters for the context cfg from its associated file. If force-load keyword argument is true (‘#t’), configuration will be reloaded even if it has already been loaded. By default, force-load is set to false (‘#f’).
Determine whether the context cfg has been successfully loaded from file.
Since 1.10.
Attempt to save configuration parameters for the context cfg to its associated file. Returns cfg. If configuration cannot be saved, raises an error.
Since 1.10.
Determine whether the context cfg has been altered since it was last synchronised with the on-disk version by loading or saving it.
Since 1.10.
A configuration context may have a parent context, from which it inherits configuration values. Configuration inheritance loops are not permitted.
See Configuration inheritance.
Return the parent context of the context cfg, if it has one. Otherwise, return ‘#f’.
Since 1.10.
Sets parent as the parent context of cfg. If parent is ‘#f’, sets cfg as having no parent context.
Note: Normally, application code should avoid using this function; keeping to the default configuration inheritance structure is recommended in order to ensure consistent behaviour of all liblepton applications.
Since 1.10.
Some configuration parameters are dangerous; in particular, parameters that may lead to arbitrary code execution need to be handled carefully. Such settings might include:
Configuration contexts can be flagged as being trusted. This allows code that needs to access such dangerous parameters to determine whether the value has been obtained from a safe source.
By default, the default context, system context and user context are trusted, and all other contexts untrusted.
Test whether cfg is a trusted configuration context.
Since 1.10.
Set whether the configuration context cfg should be trusted as a source for dangerous configuration parameters.
Warning: You should not set a configuration context as trusted unless you are certain that it originated from a safe source (e.g. by interacting with the user to verify it).
Since 1.10.
If cfg is trusted, returns cfg; otherwise, returns the first parent context of cfg that is a trusted context. If no trusted context can be found, returns ‘#f’.
Since 1.10.
Next: Configuration parameters, Up: Configuration functions [Contents][Index]