$darkmode
Elektra 0.11.0
Plugin: reference

Example: Alternative References

For this example the following configuration is used:

1 ; this example uses the ni plugin syntax
2 ; 1. metadata
3 [rootkey/ref]
4 check/reference = recursive
5 
6 [otherkey/newref]
7 check/reference = alternative
8 
9 ; 2. configuration data
10 rootkey/ref = ../otherkey
11 
12 otherkey/ref = ../yetanotherkey
13 otherkey/newref = ../otherotherkey
14 
15 otherotherkey/ref = ../nonexistent
16 otherotherkey/newref = ../mergekey
17 
18 yetanotherkey/ref = ../mergekey
19 yetanotherkey/newref = ../nonexistent
20 
21 mergekey/ref = ../finalkey
22 mergekey/newref = ../finalkey
23 
24 finalkey = ""

We mount it by executing:

1 cat << EOF > alternative.ini
2 ; this example uses the ni plugin syntax
3 ; 1. metadata
4 [rootkey/ref]
5 check/reference = recursive
6 
7 [otherkey/newref]
8 check/reference = alternative
9 
10 ; 2. configuration data
11 rootkey/ref = ../otherkey
12 
13 otherkey/ref = ../yetanotherkey
14 otherkey/newref = ../otherotherkey
15 
16 otherotherkey/ref = ../nonexistent
17 otherotherkey/newref = ../mergekey
18 
19 yetanotherkey/ref = ../mergekey
20 yetanotherkey/newref = ../nonexistent
21 
22 mergekey/ref = ../finalkey
23 mergekey/newref = ../finalkey
24 
25 finalkey = ""
26 EOF
27 
28 kdb mount alternative.ini user:/tests/reference/alternative ni reference

The file contains a specification, which marks user:/tests/reference/alternative/rootkey/ref as our root reference key and user:/tests/reference/alternative/otherkey/newref as an alternative reference.

The actual configuration contains then a structure which is processed by the plugin like follows:

  1. user:/tests/reference/alternative/rootkey/ref is read and its reference validated.
  2. user:/tests/reference/alternative/otherkey/ref is read and its reference validated.
  3. user:/tests/reference/alternative/otherkey/newref is discovered as an alternative reference and stored for later.
  4. user:/tests/reference/alternative/yetanotherkey/ref is read and its reference validated.
  5. user:/tests/reference/alternative/mergekey/ref is read and its reference validated.
  6. user:/tests/reference/alternative/finalkey does not contain a reference, so we stop here.
  7. Processing of the alternative reference chain from user:/tests/reference/alternative/otherkey/newref starts.
  8. user:/tests/reference/alternative/otherkey/newref is read and its reference validated.
  9. user:/tests/reference/alternative/otherotherkey/newref is read and its reference validated.
  10. user:/tests/reference/alternative/mergekey/newref is read and its reference validated.
  11. user:/tests/reference/alternative/finalkey does not contain a reference, so we stop here.

The resulting reference graph looks like this:

reference graph

As you can see, the plugin completely ignores user:/tests/reference/alternative/yetanotherkey/newref as well as user:/tests/reference/alternative/otherother/ref and in turn does not throw an error because user:/tests/reference/alternative/nonexistent does not exist. However, the plugin does still exhaustively check both of the alternative reference chains. If you want to prohibit this, you can set the metakey check/reference/restrict to an empty value on whichever key you want to be a leaf node in the graph.

After we are done we can unmount the example with:

1 kdb umount user:/tests/reference/alternative