
\begin{DoxyItemize}
\item infos = Information about the yanlr plugin is in keys below
\item infos/author = René Schwaiger \href{mailto:sanssecours@me.com}{\texttt{ sanssecours@me.\+com}}
\item infos/licence = B\+SD
\item infos/needs = directoryvalue yamlsmith
\item infos/provides = storage/yaml
\item infos/recommends =
\item infos/placements = getstorage
\item infos/status = maintained unittest preview experimental unfinished nodoc concept discouraged
\item infos/metadata =
\item infos/description = This storage plugin use a parser generated by A\+N\+T\+LR to read Y\+A\+ML files
\end{DoxyItemize}\hypertarget{autotoc_md861_src_plugins_yanlr_README_md}{}\section{Yan LR}\label{autotoc_md861_src_plugins_yanlr_README_md}
\hypertarget{autotoc_md861_autotoc_md862}{}\subsection{Introduction}\label{autotoc_md861_autotoc_md862}
This plugin uses A\+N\+T\+LR to generate a parser for the \href{http://yaml.org}{\texttt{ Y\+A\+ML}} serialization format. Apart from the hand written \href{/home/mpranj/workspace/libelektra/src/plugins/yanlr/yaml_lexer.cpp}{\texttt{ lexer}}, all other parts of the plugin use standard A\+N\+T\+LR tools, such as


\begin{DoxyItemize}
\item an A\+N\+T\+LR parser grammar,
\item a \href{/home/mpranj/workspace/libelektra/src/plugins/yanlr/listener.cpp}{\texttt{ listener}}, that reacts to matches in the grammar building a key set, and
\item an \href{/home/mpranj/workspace/libelektra/src/plugins/yanlr/error_listener.cpp}{\texttt{ error listener}} that reacts to syntax errors
\end{DoxyItemize}\hypertarget{autotoc_md861_autotoc_md863}{}\subsection{Dependencies}\label{autotoc_md861_autotoc_md863}
The plugin requires


\begin{DoxyItemize}
\item \href{https://www.antlr.org}{\texttt{ A\+N\+T\+LR}} {\ttfamily 4.\+6} or later, and
\item \href{https://github.com/antlr/antlr4/tree/master/runtime/Cpp}{\texttt{ A\+N\+T\+LR 4’s C++ runtime}}.
\end{DoxyItemize}

If packages for those libraries are not available for your system, you can install them manually. For more information about that please take a look \href{https://www.antlr.org}{\texttt{ at A\+N\+T\+L\+R’s homepage}} and at the \href{https://github.com/antlr/antlr4/tree/master/runtime/Cpp}{\texttt{ Read\+Me of the A\+N\+T\+LR C++ runtime}}.

Please note that we only tested the plugin with A\+N\+T\+LR {\ttfamily 4.\+7.\+1} (and later versions of A\+N\+T\+LR).\hypertarget{autotoc_md861_autotoc_md864}{}\subsubsection{Arch Linux}\label{autotoc_md861_autotoc_md864}
In \href{https://www.archlinux.org}{\texttt{ Arch Linux}} the required packages are called \href{https://www.archlinux.org/packages/extra/any/antlr4}{\texttt{ {\ttfamily antlr4}}} and \href{https://www.archlinux.org/packages/community/x86_64/antlr4-runtime}{\texttt{ {\ttfamily antlr4-\/runtime}}}.


\begin{DoxyCode}{0}
\DoxyCodeLine{pacman -Sy --noconfirm antlr4 antlr4-runtime}
\end{DoxyCode}
\hypertarget{autotoc_md861_autotoc_md865}{}\subsubsection{Debian Linux}\label{autotoc_md861_autotoc_md865}
In Debian Linux you need the packages \href{https://packages.debian.org/sid/antlr4}{\texttt{ {\ttfamily antlr4}}} and \href{https://packages.debian.org/sid/libantlr4-runtime-dev}{\texttt{ {\ttfamily libantlr4-\/runtime-\/dev}}}.


\begin{DoxyCode}{0}
\DoxyCodeLine{apt-get -y install antlr4 libantlr4-runtime-dev}
\end{DoxyCode}
\hypertarget{autotoc_md861_autotoc_md866}{}\subsubsection{mac\+OS}\label{autotoc_md861_autotoc_md866}
To install the dependencies of the plugin using \href{https://brew.sh}{\texttt{ Homebrew}}, please use the command below.


\begin{DoxyCode}{0}
\DoxyCodeLine{brew install antlr antlr4-cpp-runtime}
\end{DoxyCode}
\hypertarget{autotoc_md861_autotoc_md867}{}\subsection{Examples}\label{autotoc_md861_autotoc_md867}
\hypertarget{autotoc_md861_autotoc_md868}{}\subsubsection{Mappings}\label{autotoc_md861_autotoc_md868}
\`{}\`{}{\ttfamily  @section autotoc\+\_\+md869 Mount plugin to}user/tests/yanlr\`{} sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{autotoc_md861_autotoc_md870}{}\section{Manually add some mappings to the configuration file}\label{autotoc_md861_autotoc_md870}
printf \textquotesingle{}all \+: circles presuppose~\newline
\textquotesingle{} $>$ {\ttfamily kdb file user/tests/yanlr} printf \textquotesingle{}hello \+: world~\newline
\textquotesingle{} $>$$>$ {\ttfamily kdb file user/tests/yanlr}

kdb ls /tests/yanlr \#$>$ user/tests/yanlr/all \#$>$ user/tests/yanlr/hello

kdb get user/tests/yanlr/all \#$>$ circles presuppose\hypertarget{autotoc_md861_autotoc_md871}{}\section{Store value at root of mountpoint}\label{autotoc_md861_autotoc_md871}
kdb set user/tests/yanlr \textquotesingle{}Mount Eerie\textquotesingle{} kdb get user/tests/yanlr \#$>$ Mount Eerie\hypertarget{autotoc_md861_autotoc_md872}{}\section{Add new key-\/value pairs}\label{autotoc_md861_autotoc_md872}
\hypertarget{autotoc_md861_autotoc_md873}{}\section{Yan L\+R actually uses the Y\+A\+M\+L Smith plugin to write data}\label{autotoc_md861_autotoc_md873}
kdb set user/tests/yanlr/brand new kdb set user/tests/yanlr/brand/new eyes kdb set user/tests/yanlr/dance/gavin \textquotesingle{}Dance!\textquotesingle{}

kdb ls /tests/yanlr \#$>$ user/tests/yanlr \#$>$ user/tests/yanlr/all \#$>$ user/tests/yanlr/brand \#$>$ user/tests/yanlr/brand/new \#$>$ user/tests/yanlr/dance/gavin \#$>$ user/tests/yanlr/hello

kdb get /tests/yanlr/hello \#$>$ world kdb get user/tests/yanlr/brand \#$>$ new kdb get /tests/yanlr/dance/gavin \#$>$ Dance!\hypertarget{autotoc_md861_autotoc_md874}{}\section{Undo modifications to the key database}\label{autotoc_md861_autotoc_md874}
kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}{0}
\DoxyCodeLine{\#\#\# Arrays}
\end{DoxyCode}
 \hypertarget{autotoc_md861_autotoc_md875}{}\section{Mount plugin to $<$tt$>$/tests/yanlr$<$/tt$>$}\label{autotoc_md861_autotoc_md875}
sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{autotoc_md861_autotoc_md876}{}\section{Manually add a sequences to the configuration file}\label{autotoc_md861_autotoc_md876}
printf \textquotesingle{}primes\+:~\newline
\textquotesingle{} $>$ {\ttfamily kdb file user/tests/yanlr} printf \textquotesingle{} -\/ two~\newline
\textquotesingle{} $>$$>$ {\ttfamily kdb file user/tests/yanlr} printf \textquotesingle{} -\/ three~\newline
\textquotesingle{} $>$$>$ {\ttfamily kdb file user/tests/yanlr} printf \textquotesingle{} -\/ five~\newline
\textquotesingle{} $>$$>$ {\ttfamily kdb file user/tests/yanlr}

kdb ls user/tests/yanlr \#$>$ user/tests/yanlr/primes \#$>$ user/tests/yanlr/primes/\#0 \#$>$ user/tests/yanlr/primes/\#1 \#$>$ user/tests/yanlr/primes/\#2

kdb set user/tests/yanlr/primes/\#3 seven\hypertarget{autotoc_md861_autotoc_md877}{}\section{Retrieve index of last array element}\label{autotoc_md861_autotoc_md877}
kdb meta-\/get user/tests/yanlr/primes array \#$>$ \#3\hypertarget{autotoc_md861_autotoc_md878}{}\section{Undo modifications to the key database}\label{autotoc_md861_autotoc_md878}
kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}{0}
\DoxyCodeLine{\#\#\# Boolean Values}
\end{DoxyCode}
 \hypertarget{autotoc_md861_autotoc_md879}{}\section{Mount plugin to $<$tt$>$/tests/yanlr$<$/tt$>$}\label{autotoc_md861_autotoc_md879}
sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{autotoc_md861_autotoc_md880}{}\section{Manually add a boolean value to the database}\label{autotoc_md861_autotoc_md880}
printf \textquotesingle{}boolean\+: true\textquotesingle{} $>$ {\ttfamily kdb file user/tests/yanlr}\hypertarget{autotoc_md861_autotoc_md881}{}\section{Elektra stores boolean values as $<$tt$>$0$<$/tt$>$ and $<$tt$>$1$<$/tt$>$}\label{autotoc_md861_autotoc_md881}
kdb get user/tests/yanlr/boolean \#$>$ 1\hypertarget{autotoc_md861_autotoc_md882}{}\section{Undo modifications to the key database}\label{autotoc_md861_autotoc_md882}
kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}{0}
\DoxyCodeLine{\#\#\# Null Values}
\end{DoxyCode}
 \hypertarget{autotoc_md861_autotoc_md883}{}\section{Mount plugin to $<$tt$>$/tests/yanlr$<$/tt$>$}\label{autotoc_md861_autotoc_md883}
sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{autotoc_md861_autotoc_md884}{}\section{Manually add a null value to the database}\label{autotoc_md861_autotoc_md884}
printf \textquotesingle{}\char`\"{}null\char`\"{}\+:\textquotesingle{} $>$ {\ttfamily kdb file user/tests/yanlr}\hypertarget{autotoc_md861_autotoc_md885}{}\section{Elektra adds the metakey $<$tt$>$binary$<$/tt$>$ for empty keys}\label{autotoc_md861_autotoc_md885}
kdb meta-\/ls user/tests/yanlr/null \#$>$ binary\hypertarget{autotoc_md861_autotoc_md886}{}\section{Undo modifications to the key database}\label{autotoc_md861_autotoc_md886}
kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}{0}
\DoxyCodeLine{\#\#\# Error Messages}
\end{DoxyCode}
 \hypertarget{autotoc_md861_autotoc_md887}{}\section{Mount plugin}\label{autotoc_md861_autotoc_md887}
sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{autotoc_md861_autotoc_md888}{}\section{Manually add syntactically incorrect data}\label{autotoc_md861_autotoc_md888}
printf -- \textquotesingle{}key\+: -\/ element 1~\newline
\textquotesingle{} $>$ {\ttfamily kdb file user/tests/yanlr} printf -- \textquotesingle{}-\/ element 2 \# Incorrect Indentation!\textquotesingle{} $>$$>$ {\ttfamily kdb file user/tests/yanlr}\hypertarget{autotoc_md861_autotoc_md889}{}\section{The plugin reports the location of the error}\label{autotoc_md861_autotoc_md889}
kdb ls user/tests/yanlr \hypertarget{autotoc_md861_autotoc_md890}{}\section{R\+E\+T\+: 5}\label{autotoc_md861_autotoc_md890}
\hypertarget{autotoc_md861_autotoc_md891}{}\section{S\+T\+D\+E\+R\+R\+: .$\ast$/config.\+yaml\+:2\+:1\+: mismatched input \textquotesingle{}-\/ \textquotesingle{} expecting end of map.$\ast$}\label{autotoc_md861_autotoc_md891}
\hypertarget{autotoc_md861_autotoc_md892}{}\section{Let us look at the error message more closely.}\label{autotoc_md861_autotoc_md892}
\hypertarget{autotoc_md861_autotoc_md893}{}\section{Since the location of $<$tt$>$config.\+yaml$<$/tt$>$ depends on the current user and O\+S,}\label{autotoc_md861_autotoc_md893}
\hypertarget{autotoc_md861_autotoc_md894}{}\section{we store the text before $<$tt$>$config.\+yaml$<$/tt$>$ as $<$tt$>$user/tests/error/prefix$<$/tt$>$.}\label{autotoc_md861_autotoc_md894}
kdb set user/tests/error \char`\"{}\$(2$>$\&1 kdb ls user/tests/yanlr)\char`\"{} kdb set user/tests/error/prefix \char`\"{}\$(kdb get user/tests/error $\vert$ grep \textquotesingle{}config.\+yaml\textquotesingle{} $\vert$ head -\/1 $\vert$ sed -\/\+E \textquotesingle{}s/(.$\ast$)config.\+yaml.$\ast$/\textbackslash{}1/\textquotesingle{})\char`\"{} \hypertarget{autotoc_md861_autotoc_md895}{}\section{We also store the length of the prefix, so we can remove it from every}\label{autotoc_md861_autotoc_md895}
\hypertarget{autotoc_md861_autotoc_md896}{}\section{line of the error message.}\label{autotoc_md861_autotoc_md896}
kdb set user/tests/error/prefix/length \char`\"{}\$(kdb get user/tests/error/prefix $\vert$ wc -\/c $\vert$ sed \textquotesingle{}s/\mbox{[} \mbox{]}$\ast$//g\textquotesingle{})\char`\"{}\hypertarget{autotoc_md861_autotoc_md897}{}\section{Since we only want to look at the “reason” of the error, we}\label{autotoc_md861_autotoc_md897}
\hypertarget{autotoc_md861_autotoc_md898}{}\section{remove the other part of the error message with $<$tt$>$head$<$/tt$>$ and $<$tt$>$tail$<$/tt$>$.}\label{autotoc_md861_autotoc_md898}
kdb get user/tests/error $\vert$ tail -\/n6 $\vert$ cut -\/c\char`\"{}\$(kdb get user/tests/error/prefix/length $\vert$ tr -\/d \textquotesingle{}\textbackslash{}n\textquotesingle{})\char`\"{}-\/ \#$>$ config.\+yaml\+:2\+:1\+: mismatched input \textquotesingle{}-\/ \textquotesingle{} expecting end of map \#$>$ -\/ element 2 \# Incorrect Indentation! \#$>$ $^\wedge$$^\wedge$ \#$>$ config.\+yaml\+:2\+:37\+: extraneous input \textquotesingle{}end of map\textquotesingle{} expecting end of document \#$>$ -\/ element 2 \# Incorrect Indentation! \#$>$ $^\wedge$\hypertarget{autotoc_md861_autotoc_md899}{}\section{Fix syntax error}\label{autotoc_md861_autotoc_md899}
printf -- \textquotesingle{}key\+: -\/ element 1~\newline
\textquotesingle{} $>$ {\ttfamily kdb file user/tests/yanlr} printf -- \textquotesingle{} -\/ element 2 \# Fixed!\textquotesingle{} $>$$>$ {\ttfamily kdb file user/tests/yanlr}

kdb ls user/tests/yanlr \#$>$ user/tests/yanlr/key \#$>$ user/tests/yanlr/key/\#0 \#$>$ user/tests/yanlr/key/\#1\hypertarget{autotoc_md861_autotoc_md900}{}\section{Undo modifications}\label{autotoc_md861_autotoc_md900}
kdb rm -\/r user/tests/error kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}{0}
\DoxyCodeLine{\#\# Limitations}
\DoxyCodeLine{}
\DoxyCodeLine{- The plugin does **not support**}
\DoxyCodeLine{}
\DoxyCodeLine{  - plain scalars that span **multiple lines**,}
\DoxyCodeLine{  - **special characters** inside double quoted scalars,}
\DoxyCodeLine{  - other **line endings** than `\(\backslash\)n` (Unix line endings),}
\DoxyCodeLine{  - **block scalars**,}
\DoxyCodeLine{  - **flow collections**,}
\DoxyCodeLine{  - **tags**,}
\DoxyCodeLine{  - **anchors \& aliases**,}
\DoxyCodeLine{  - **multiple documents**, and}
\DoxyCodeLine{  - document **start and end markers**}
\DoxyCodeLine{}
\DoxyCodeLine{  .}
\DoxyCodeLine{}
\DoxyCodeLine{- Yan LR does not provide write support for data. Please use the [YAML Smith](@ref src\_plugins\_yamlsmith\_README\_md) plugin for that purpose.}
\DoxyCodeLine{}
\DoxyCodeLine{\#\#\# Input Restrictions}
\DoxyCodeLine{}
\DoxyCodeLine{The plugin should, but does not, limit the amount}
\DoxyCodeLine{}
\DoxyCodeLine{- of **nesting levels**,}
\DoxyCodeLine{- the **length of numbers**, and}
\DoxyCodeLine{- the **length of scalars**}
\DoxyCodeLine{}
\DoxyCodeLine{. These restrictions would make it less easy to crash the parser, by feeding it unrestricted data.}
\DoxyCodeLine{}
\DoxyCodeLine{\#\#\# Duplicate Keys}
\DoxyCodeLine{}
\DoxyCodeLine{Currently the plugin parses the input}
\DoxyCodeLine{}
\DoxyCodeLine{```yaml}
\DoxyCodeLine{duplicate: one}
\DoxyCodeLine{duplicate: two}
\end{DoxyCode}


storing the value {\ttfamily two}. According to the Y\+A\+ML specification the parser should not allow duplicated keys, and instead fail with an error, for the input above.