
\begin{DoxyItemize}
\item infos = Information about keytometa plugin is in keys below
\item infos/author = Felix Berlakovich \href{mailto:elektra@berlakovich.net}{\texttt{ elektra@berlakovich.\+net}}
\item infos/licence = BSD
\item infos/provides = conv
\item infos/needs =
\item infos/placements = presetstorage postgetstorage
\item infos/status = unittest tested nodep libc configurable discouraged
\item infos/metadata =
\item infos/description = conversion of keys to metakeys and vice versa
\end{DoxyItemize}\hypertarget{md_src_plugins_keytometa_README_src_plugins_keytometa_README_md}{}\doxysection{Introduction}\label{md_src_plugins_keytometa_README_src_plugins_keytometa_README_md}
\begin{quote}
Note\+: This plugin uses a deprecated way to store comments. \end{quote}
This plugin converts keys into metakeys of other keys. The keys to be converted are tagged with special metadata. Converting keys into metakeys basically raises two questions\+:


\begin{DoxyItemize}
\item which keys should be converted
\item which key to append the resulting metakeys to
\end{DoxyItemize}

The keys to be converted are identified by metakeys below {\ttfamily convert} (e.\+g. {\ttfamily convert/append}). The keys receiving the resulting metadata are identified by append strategies. The plugin currently supports the following metakeys for controlling the conversion\+:


\begin{DoxyItemize}
\item {\ttfamily convert/metaname} specifies the name of the resulting metakey. For example tagging the key {\ttfamily user\+:/config/key1} with {\ttfamily convert/metaname = comment} means that the key will be converted to a metakey with the name {\ttfamily comment}.
\item {\ttfamily convert/append} specifies the append strategy (see below)
\item {\ttfamily convert/append/samelevel} specifies that the key should only be written to the metadata of a key with the same hierarchy level (see below).
\end{DoxyItemize}

The keys converted to metadata are restored as soon as the keyset is written back. However, the plugin is stateful. This means that a keyset must be read and keys must be converted by the plugin in order to undo this conversion in the set direction. Modifications to the metadata which resulted from converted keys are propagated back to the corresponding key (see merging for more details).

The keys are ordered by the \char`\"{}order\char`\"{} metadata. If two keys are equal according to the order metadata, they are ordered by name instead.\hypertarget{md_src_plugins_keytometa_README_autotoc_md292}{}\doxysection{Installation}\label{md_src_plugins_keytometa_README_autotoc_md292}
See \mbox{\hyperlink{doc_INSTALL_md}{installation}}. The package is called {\ttfamily libelektra5-\/extra}.\hypertarget{md_src_plugins_keytometa_README_autotoc_md293}{}\doxysection{Append Strategies}\label{md_src_plugins_keytometa_README_autotoc_md293}
The append strategy specifies which key will receive the resulting metadata. Currently the plugin supports the following strategies\+:\hypertarget{md_src_plugins_keytometa_README_autotoc_md294}{}\doxysubsection{Parent Strategy}\label{md_src_plugins_keytometa_README_autotoc_md294}
The metadata is added to the first existing parent of the converted key. This does not necessarily have to be the parent of the keyset. If no such key is found, the first key in a sorted keyset will receive the metadata (this is usually the parent key of the keyset). For example consider the following keyset\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{user:/config/key1}
\DoxyCodeLine{user:/config/key1/child1}
\DoxyCodeLine{user:/config/key2}
\DoxyCodeLine{user:/config/key2/deeper/child2}
\DoxyCodeLine{user:/config/child3}

\end{DoxyCode}


If child1, child2 and child3 were tagged with {\ttfamily convert/append = parent}, key1 would receive the metadata from child1 and child3. Key2 would receive the metadata from child2.\hypertarget{md_src_plugins_keytometa_README_autotoc_md295}{}\doxysubsection{Next Strategy}\label{md_src_plugins_keytometa_README_autotoc_md295}
The metadata is added to the key following the converted key in a sorted keyset. If no such key is found (for example because the key to be converted is the last one), the strategy is reverted to parent. For example consider the following keyset\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{user:/config/deeper/key1}
\DoxyCodeLine{user:/config/key2}
\DoxyCodeLine{user:/config/key3}
\DoxyCodeLine{user:/config/key4}

\end{DoxyCode}


If key1 and key3 were tagged with {\ttfamily convert/append = next}, key2 would receive the metadata resulting from key1 and key4 would receive the metadata resulting from key3.\hypertarget{md_src_plugins_keytometa_README_autotoc_md296}{}\doxysubsection{Previous Strategy}\label{md_src_plugins_keytometa_README_autotoc_md296}
The metadata is added to the key preceding the converted key in a sorted keyset. If no such key is found (for example because the key to be converted is the first one), the strategy is reverted to parent. For example consider the following keyset\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{user:/config/key1}
\DoxyCodeLine{user:/config/deeper/key2}
\DoxyCodeLine{user:/config/key3}
\DoxyCodeLine{user:/config/key4}

\end{DoxyCode}


If key2 and key4 were tagged with {\ttfamily convert/append = previous}, key1 would receive the metadata resulting from key2 and key3 would receive the metadata resulting from key4.\hypertarget{md_src_plugins_keytometa_README_autotoc_md297}{}\doxysection{Merging}\label{md_src_plugins_keytometa_README_autotoc_md297}
The metadata resulting from a converted key is never appended to another key which is going to be converted. This prevents that the data of converted keys is invisible after the conversion. Instead the metadata resulting from different converted keys with the same append strategy is merged together (separated by a newline). Keys with different append strategies are skipped, until either a key with the same strategy is found (which is simply merged as described above) or the target key is found. The keys are always processed in the order of an ordered keyset. For example consider the following keyset\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{user:/config/key0}
\DoxyCodeLine{user:/config/key1 = value1}
\DoxyCodeLine{user:/config/key2 = value2}
\DoxyCodeLine{user:/config/key3 = value3}
\DoxyCodeLine{user:/config/key4 = value4}
\DoxyCodeLine{user:/config/key5}

\end{DoxyCode}


If key1 and key2 were tagged with {\ttfamily convert/append = next} and key3 and key4 were tagged with {\ttfamily convert/append = previous} the following would happen\+:


\begin{DoxyItemize}
\item the resulting metadata of key0 would contain {\ttfamily value3\textbackslash{}nvalue4} (the values of key3 and key4 are merged together and key1 and key2 are skipped, as they have different append strategy)
\item the resulting metadata of key5 would contain {\ttfamily value1\textbackslash{}nvalue2} (the values of key1 and key2 are merged together and key3 and key4 are skipped, as they have different append strategy)
\end{DoxyItemize}\hypertarget{md_src_plugins_keytometa_README_autotoc_md298}{}\doxysubsection{Same-\/\+Level Appending}\label{md_src_plugins_keytometa_README_autotoc_md298}
The option {\ttfamily convert/append/samelevel} can be used to force that the metadata is only appended to a key on the same hierarchy level. If no such key is found, the strategy is reverted to parent. Note, that the value of the samelevel key does not matter. Only its existence is relevant. For example consider the following keyset\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{user:/config/key0}
\DoxyCodeLine{user:/config/key1/child1}
\DoxyCodeLine{user:/config/key2}
\DoxyCodeLine{user:/config/key3/child2}
\DoxyCodeLine{user:/config/key4}
\DoxyCodeLine{user:/config/key5}
\DoxyCodeLine{user:/config/key6}

\end{DoxyCode}


If child1, child2 and key4 were each tagged with {\ttfamily convert/append = next} and child2 and key4 were tagged with {\ttfamily convert/append/samelevel}, key2 would receive the metadata resulting from child1. key0 would receive the metadata resulting from child2 (strategy reverted to parent, as the samelevel request cannot be fulfilled). key5 would receive the metadata resulting from key4.\hypertarget{md_src_plugins_keytometa_README_autotoc_md299}{}\doxysection{Real World Example}\label{md_src_plugins_keytometa_README_autotoc_md299}
The keytometa plugin was initially developed to aid the integration of the Augeas plugin. The Augeas plugin represents comments in configuration files as keys. However, in Elektra comments are usually represented within comment metakeys. Therefore it would be desirable to convert all comment keys to comment metakeys. This is achieved by adding the following to the Augeas plugin contract.


\begin{DoxyCode}{0}
\DoxyCodeLine{\textcolor{comment}{// ...}}
\DoxyCodeLine{\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}system:/elektra/modules/augeas/config/needs/glob/get/\#1"{}},}
\DoxyCodeLine{    \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}*\#comment*"{}},}
\DoxyCodeLine{    \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a040582834bb2d90049947d7ef74e87e2}{KEY\_META}}, \textcolor{stringliteral}{"{}convert/metaname"{}}, \textcolor{stringliteral}{"{}comment/\#0"{}},}
\DoxyCodeLine{    \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8a040582834bb2d90049947d7ef74e87e2}{KEY\_META}}, \textcolor{stringliteral}{"{}convert/append"{}}, \textcolor{stringliteral}{"{}next"{}},}
\DoxyCodeLine{    \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}}),}
\DoxyCodeLine{\mbox{\hyperlink{group__key_gad23c65b44bf48d773759e1f9a4d43b89}{keyNew}} (\textcolor{stringliteral}{"{}system:/elektra/modules/augeas/config/needs/glob/get/\#1/flags"{}},}
\DoxyCodeLine{    \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8ac66e4a49d09212b79f5754ca6db5bd2e}{KEY\_VALUE}}, \textcolor{stringliteral}{"{}"{}}, \textcolor{comment}{/* disable the path matching mode */}}
\DoxyCodeLine{    \mbox{\hyperlink{group__key_gga9b703ca49f48b482def322b77d3e6bc8aa8adb6fcb92dec58fb19410eacfdd403}{KEY\_END}})}
\DoxyCodeLine{\textcolor{comment}{// ...}}
\DoxyCodeLine{;}

\end{DoxyCode}


Tagging the keys to be converted to comment metakeys happens via the glob plugin. The metadata set on the key {\ttfamily glob/get/\#1} is copied to each key that matches the pattern {\ttfamily $\ast$\#comment$\ast$}, i.\+e. each comment key generated by the Augeas plugin. {\ttfamily convert/metaname = comment} because we want the comment keys to be converted to the comment metadata. {\ttfamily convert/append = next} is chosen because usually comments occur before the key they describe. 