Next: Configuration parameters, 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:

- Preferred PDF reader
- Preferred web browser
- Search path for Scheme plugins

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]