
\begin{DoxyItemize}
\item infos = Information about the xerces plugin is in keys below
\item infos/author = Armin Wurzinger \href{mailto:e1528532@libelektra.org}{\tt e1528532@libelektra.\+org}
\item infos/licence = B\+SD
\item infos/provides = storage/xml
\item infos/needs =
\item infos/placements = getstorage setstorage
\item infos/status = recommended maintained unittest memleak
\item infos/metadata = xerces/rootname
\item infos/description = Storage in the X\+ML format.
\end{DoxyItemize}

This plugin is a storage plugin allowing Elektra to read and write X\+ML formatted files. It uses a general format which\+:


\begin{DoxyItemize}
\item Maps key names to X\+ML elements
\item Maps key values to textual content of X\+ML elements
\item Maps metakeys to X\+ML attributes. Metakey name = attribute name, Metakey value = attribute value
\item Ignores X\+ML comments
\end{DoxyItemize}

\subsection*{Usage}

To mount an X\+ML file we use\+:


\begin{DoxyCode}
kdb mount file.xml user/test/file xerces
\end{DoxyCode}


The strength and usage of this plugin is that it supports arbitrary X\+ML files and does not require a specific format. Given the following example of an X\+ML file\+:


\begin{DoxyCode}
<?\textcolor{keyword}{xml} \textcolor{keyword}{version}=\textcolor{stringliteral}{"1.0"} \textcolor{keyword}{encoding}=\textcolor{stringliteral}{"UTF-8"} \textcolor{keyword}{standalone}=\textcolor{stringliteral}{"no"} ?>
<\textcolor{keywordtype}{xerces}>\textcolor{keyword}{foo}
  <\textcolor{keywordtype}{bar} \textcolor{keyword}{meta}=\textcolor{stringliteral}{"da\_ta"}>\textcolor{keyword}{bar}</\textcolor{keywordtype}{bar}>
</\textcolor{keywordtype}{xerces}>
\end{DoxyCode}


Please note that if the key name does not correspond to the root element of the xml file, the original name gets stored in a metakey called {\ttfamily xerces/rootname}. The content of the root element gets mapped to the mount point.

We can observe the following result after mounting\+:


\begin{DoxyCode}
kdb get user/test/file
#> foo
kdb get user/test/file/bar
#> bar
kdb getmeta user/test/file/bar meta
#> da\_ta
\end{DoxyCode}


To export an existing keyset to the X\+ML format\+:


\begin{DoxyCode}
kdb export user/test/xerces xerces > example.xml
\end{DoxyCode}


The root element of the resulting X\+ML file will be \char`\"{}xerces\char`\"{} again, restored via the metadata. If you don\textquotesingle{}t want this behavior, delete the metadata {\ttfamily xerces/rootname} on the mount point, then it uses the mount point\textquotesingle{}s name instead.

\subsection*{Dependencies}


\begin{DoxyItemize}
\item {\ttfamily Xerces-\/\+C++ 3.\+0.\+0} or newer ({\ttfamily apt-\/get install libxerces-\/c-\/dev})
\item C\+Make 3.\+6 or a copy of {\ttfamily Find\+Xerces\+C.\+cmake} in {\ttfamily /usr/share/cmake-\/3.0/\+Modules/}
\end{DoxyItemize}

\subsection*{Limitations}

This plugin is not able to handle key names which contain characters that are not allowed to appear as an X\+ML element name. Consider using the rename plugin to take care about proper escaping.

The main rules of an X\+ML element name are\+:


\begin{DoxyItemize}
\item Element names must start with a letter or underscore
\item Element names cannot start with the letters xml (or X\+ML, or Xml, etc.)
\item Element names can contain letters, digits, hyphens, underscores, and periods
\item Element names cannot contain spaces
\end{DoxyItemize}

The root key is not allowed to be an array, as this would correspond to multiple root elements in X\+ML (see the \href{https://github.com/ElektraInitiative/libelektra/issues/1451}{\tt Git\+Hub issue}).

X\+SD transformations, schemas or D\+T\+Ds are not supported yet.

\subsection*{Examples}

\subsubsection*{Mounting, setting a key and exporting}


\begin{DoxyCode}
# Backup-and-Restore:user/tests/xercesfile

sudo kdb mount xerces.xml user/tests/xercesfile xerces

kdb set user/tests/xercesfile foo
kdb setmeta user/tests/xercesfile xerces/rootname xerces
kdb set user/tests/xercesfile/bar bar
kdb setmeta user/tests/xercesfile/bar meta "da\_ta"

kdb getmeta user/tests/xercesfile xerces/rootname
#> xerces

kdb get user/tests/xercesfile/bar
#> bar

kdb export user/tests/xercesfile xerces
# STDOUT-REGEX: <bar meta="da\_ta">bar</bar>

sudo kdb rm -r user/tests/xercesfile
sudo kdb umount user/tests/xercesfile
\end{DoxyCode}
 