$darkmode
Elektra 0.11.0
|
This tutorial assumes that you are already familiar with namespaces. This tutorial will only explain cascading lookup.
When Elektra looks up a cascading key (i.e. key names without a namespace and a leading slash /
, the namespaces are searched in the following order:
.git
or .htaccess
)If a key, for example, exists in both user and system namespace, the key in the user namespace takes precedence over the one in the system namespace. If there is no such key in the user namespace the key in the system namespace acts as a fallback.
But let's demonstrate this with an example:
Configuration in the system namespace is the same for all users. Therefore, this namespace provides a default or fallback configuration.
With the default Elektra installation only an administrator can update configuration settings within the system namespace.
A user may now want to override the configuration in system, so he/she sets a key in the user namespace:
Note that configuration in the user namespace only affects this user. Other users would still get the key from the system namespace.
The dir namespace is associated with a directory. The configuration in the dir namespace applies to the current working directory and all its subdirectories. This is useful if you have project specific settings (e.g. your Git configuration or a .htaccess file).
As dir precedes the user namespace, configuration in dir can overwrite user configuration:
The proc namespace is not accessible by the command line tool kdb, as it is unique for each running process using Elektra. So we have to omit an example for this namespace at this point. Elektrified applications can use this namespace to override configuration from other namespaces internally.
The spec namespace is used to store metadata about keys and therefore Elektra handles the spec namespace differently to other namespaces. The following part of the tutorial is dedicated to the impact of the spec namespace on cascading lookups.
If a value is to be written to a cascading key, i.e., a key starting with '/', only cascading keys that resolve to an existing key will be used.
For example,
will both fail, as no matching key exists. Since there are multiple hypothetical key names that would match the cascading name (keys of specific namespaces like user:, system:, ...) if they existed, it is not clear what the user intended and thus an error is produced.
To make the previous two operations meaningful, a matching key in the user: namespace is created:
Now, the operations operate on a well-defined key and succeed this time:
The spec
namespace is special as it can completely change how the cascading lookup works.
During a cascading lookup for a specific key, the default Elektra behavior can be changed by a corresponding spec-key
, i.e. a key in the spec namespace with the same name.
For example, the metadata override/#0
of the respective spec-key
can be specified to use a different key in favor of the key itself. This way, we can implement a redirect or symlink like behavior and therefore even config from current folder (dir
namespace) can be overwritten.
The cascading lookup will consider the following metadata keys of spec-key
:
override/#n
redirect to one of the specified keysnamespaces/#n
specifies which namespaces will be considered and in which orderfallback/#n
if no key was found these keys will act as a fallbackdefault
defines a default value for the key if none of the keys was foundNote: override/#n
, namespaces/#n
and fallback/#n
are Elektra array keys. This means, such keys can exist several times, each with a different number for n
, e.g. override/#0
, override/#1
... This way, we can define multiple values for a specific key with a defined order.
As you can see, override links are considered before everything else, which makes them really powerful.
Consider the following example:
First, we create a target key to demonstrate the override link mechanism:
Override links can be defined by adding them to the override/#
metadata array key of the corresponding spec-key
:
Now when doing a cascading lookup, we get the value of our target key instead of the specified one:
As we used a cascading key for our override link (/tests/overrides/test
) we can use this to allow users to provide their own tests/overrides/test
keys. If a user sets the /tests/overrides/test
key, the user namespace will be used (for a non-root user) and therefore the new target for our /tests/tutorial/cascading/#0/current/test
key will be user:/tests/overrides/test
instead of system:/tests/overrides/test
.
Furthermore, you can specify a custom order for the namespaces, set fallback keys and more. For more information, read the `elektra-spec` help page.
As last part in this tutorial we remove the modifications to the database we made previously.