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


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

Three special contexts are always automatically defined: the default context, the system context and the user context. The user context is the default parent context for all other configuration contexts, including newly-created ones.

2.4.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 geda.conf. If path is not a directory, it is truncated, and then a file named geda.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 geda.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).

Function: system-config-context

The system context is used for system-wide configuration. Its parent context is the default context. It is located:

  1. By searching XDG_CONFIG_DIRS for a gEDA/geda-system.conf file.
  2. By checking the system configuration directory specified at compile-time for a gEDA/geda-system.conf file.
Function: user-config-context

The user context is used for user-specific configuration, and is loaded from gEDA/geda-user.conf in XDG_CONFIG_HOME. Its parent context is the system context.

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

Function: config-load! cfg

Attempt to load configuration parameters for the context cfg from its associated file.

Function: config-loaded? cfg

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

Function: config-save! cfg

Attempt to save configuration parameters for the context cfg to its associated file.

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.

2.4.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: context-parent cfg

Return the parent context of the context cfg, if it has one.

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 libgeda applications.

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

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

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


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