Next: , Up: Configuration functions   [Contents][Index]


2.5.1 Configuration contexts

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.

2.5.1.1 Obtaining a context

Function: path-config-context path

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.

Function: default-config-context

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.

Function: system-config-context

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.

Function: user-config-context

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.

Function: cache-config-context

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.

Function: anyfile-config-context path [parent] [trusted]

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’.

Function: config? cfg

Returns ‘#t’ if and only if cfg is a configuration context object.

2.5.1.2 Loading and saving configuration files

Other than the default context, all configuration contexts are associated with an on-disk configuration file.

Function: config-filename cfg

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.

Function: config-load! cfg [force-load]

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’).

Function: config-loaded? cfg

Determine whether the context cfg has been successfully loaded from file.

Since 1.10.

Function: config-save! cfg

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.

Function: config-changed? cfg

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.

2.5.1.3 Context parents

A configuration context may have a parent context, from which it inherits configuration values. Configuration inheritance loops are not permitted.

See Configuration inheritance.

Function: config-parent cfg

Return the parent context of the context cfg, if it has one. Otherwise, return ‘#f’.

Since 1.10.

Function: set-config-parent! cfg parent

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.

2.5.1.4 Context trust

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.

Function: config-trusted? cfg

Test whether cfg is a trusted configuration context.

Since 1.10.

Function: set-config-trusted! cfg trusted?

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.

Function: config-trusted-context cfg

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]