.TH "autotoc_md559" 3elektra "Sun Nov 15 2020" "Version 0.9.3" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
autotoc_md559Plugin: reference 
 \- 
.SH "Example: Validating Complex Recursive Structures"
.PP
Suppose you have some mutually recursive \fCstruct\fPs in C\&. You want to map this structure onto a hierarchy inside your KDB\&. This by itself was always possible, but the reference plugin in combination with the spec plugin, now allows for this in a way that can be validated and checked by Elektra\&.
.PP
The structure we will use for this example is easily defined in C code:
.PP
.PP
.nf
struct typeA {
  char *name;
  struct typeB *ref;
};

struct typeB {
  long int id;
  struct typeA *ref;
};

struct typeA *rootkey_ref;
.fi
.PP
.PP
Starting with a reference to an element of type \fCtypeA\fP, we except an alternating chain of \fCtypeA\fP and \fCtypeB\fP\&. In this chain each element of type \fCtypeA\fP shall have a string attached to it, while elements of type \fCtypeB\fP shall contain an integer\&.
.PP
The specification used for such a structure is as follows (using the syntax of the \fCni\fP plugin):
.PP
.PP
.nf
[rootkey/ref]
check/reference = recursive
check/reference/restrict = \&.\&./typeA/_

[typeA/_]
default = ""

[typeA/_/name]
check/type = string

[typeA/_/ref]
check/reference/restrict = \&.\&./\&.\&./typeB/_

[typeB/_]
default = ""

[typeB/_/id]
check/type = long

[typeB/_/ref]
check/reference/restrict = \&.\&./\&.\&./typeA/_
.fi
.PP
.PP
The basic idea is to use the keys \fCtypeA\fP and \fCtypeB\fP as a sort of 'directory', in which every 'file' represent an element of type \fCtypeA\fP or type \fCtypeB\fP respectively\&.
.PP
To achieve our goals of type validation, we specify \fCrootkey/ref\fP to be the root of our reference graph, but also restrict the possible reference to keys directly below \fCtypeA\fP\&. That way we ensure that any reference set in \fCrootkey/ref\fP will refer to a key which is, validated to be compatible with our \fCstruct typeA\fP by the spec and type plugins\&.
.PP
Using the spec plugin we then specify all direct children of \fCtypeA\fP to have a default value of \fC''\fP\&. This ensures that these keys exist and therefore can be referenced\&. \fC¹\fP Then we simply specify the \fCname\fP sub-key for all of these children to be a string, and restrict the possible reference to direct children of \fCtypeB\fP\&. From there we proceed similarly for the children of \fCtypeB\fP and we are done\&. 
.PP
.PP
¹ It would actually be better to only give these keys a value, if the \fCname\fP sub-key exists, but there is currently no good way to do that in Elektra\&. An alternative would be to use the keys themselves, i\&.e\&. give them an actual value\&.