NAME

       md_src_plugins_struct_README - README

       • infos = Information about struct plugin is in keys below

       • infos/author = Markus Raab elektra@libelektra.org

       • infos/licence = BSD

       • infos/needs =

       • infos/provides = apply

       • infos/ordering = check

       • infos/placements = presetstorage

       • infos/description = Copies meta data to keys using structbing

       This  plugin  is a check plugin which checks the structure and interrelations of Keys in order the verify
       that they represent a valid configuration.

   Purpose
       The glob plugin together with the check plugins create a good combination to check keys which are present
       in the KeySet. For some storage plugins like fstab, however, missing keys are as fatal as not  validating
       keys – it is not possible to write a valid configuration file without them.

       The  problem  can  be described as a structure built with lists and other structures that must match with
       the key names of a KeySet. If a structure must have an element, contrary to glob, the plugin can yield an
       error if it is missing. During the matching, the plugin also applies metadata  to  the  individual  keys.
       Such  plugins  that check the structure and interrelations of keys are called structure checker. They can
       require that various subkeys have to or must not exist.  This  can  happen  recursively  to  specify  any
       structure.

       The  struct  plugin implements such a behaviour. It allows enforcement of a strong consistency within the
       keys of one backend.

   Usage
       In order for the struct plugin to do its job, it needs a plugin configuration to know which structure  it
       should check for. This configuration can be passed from a storage plugin’s config/needs clause.

   Example
       The  fstab  plugin  uses  the  struct plugin to verify the correct structure. Here is a snippet from it's
       contract:

           keyNew ("system/elektra/modules/fstab/config/needs/struct",
           KEY_VALUE, "list FStab",
           KEY_END),
           keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab",
           KEY_META, "check/type", "null empty",
           KEY_END),
           keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab/device",
           KEY_META, "check/type", "string",
           KEY_META, "check/path", "device",
           KEY_END),
           keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab/mpoint",
           KEY_META, "check/type", "string",
           KEY_META, "check/path", "directory",
           KEY_END),
           keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab/type",
           KEY_META, "check/type", "FSType",
           KEY_END),
           keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab/options",
           KEY_META, "check/type", "string",
           KEY_END),
           keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab/dumpfreq",
           KEY_META, "check/type", "unsigned_short",
           KEY_END), keyNew ("system/elektra/modules/fstab/config/needs/struct/FStab/passno",
           KEY_META, "check/type", "unsigned_short",
           KEY_END),

       The key value of needs/struct within the plugin configuration marks the starting  point.  list  describes
       the  first  structure  to be generated. It is a built-in structure of the struct plugin that supports all
       subkeys in one level. It applies to every direct subkey the structure  check  received  by  the  template
       parameter.  The  template  parameter is, in this case, FStab. The rest of the configuration specifies how
       entries of FStab must look.

       The information applied to the keys is given through metadata. This metadata is copied to each key during
       the structure check. If,however,a key is missing,the structure check will terminate with a  failure.  Any
       additional key will also lead to an error.

       The  metadata  may  be evaluated by subsequent checks. In the situation of fstab a typechecker and a path
       checker are both useful.

       The purpose of such structure checks is that only a valid configuration can be stored  and  that  neither
       applications nor storage plugins are surprised by configuration they do not understand.

       The  fstab  plugin  trusts  the fact that no invalid configuration is passed. It does not check it again.
       Missing configuration would lead to partially set data structures.  The  internally  used  API  setmntent
       crashes  in  that  case.  This  leads us to the {purpose of contracts}: We want a guarantee that specific
       conditions are already met because we know that the code of the plugin cannot handle it.

       Let us look at a different scenario with the same configuration. Instead of using the  fstab  plugin,  we
       will  use  a general purpose storage plugin. For example, the dump plugin. Note that the metadata will be
       stored permanently in this situation. No plugin exports a config/needs clauses for the struct  plugin  in
       this situation. But the user can add the struct plugin and the plugin configuration, as shown in the code
       above, to the backend manually. Applications still can be sure that only a specific configuration will be
       stored and passed to them. The unwritten contract is between the application and the backend. No contract
       checker, however, would detect the missing configuration.

   Limitation
       This  approach  for  defining  the structure works recursively. Every element can have a value with a new
       structure  check.  Additionally,  multiple  template  parameters  can  support  even  more  generic  data
       structures. This is, however, not yet implemented.

Version 0.8.14                                   Tue Dec 15 2015          md_src_plugins_struct_README(3elektra)