
\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{md_src_plugins_yanlr_README_src_plugins_yanlr_README_md}{}\doxysection{Yan LR}\label{md_src_plugins_yanlr_README_src_plugins_yanlr_README_md}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md849}{}\doxysubsection{Introduction}\label{md_src_plugins_yanlr_README_autotoc_md849}
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{md_src_plugins_yanlr_README_autotoc_md850}{}\doxysubsection{Dependencies}\label{md_src_plugins_yanlr_README_autotoc_md850}
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{md_src_plugins_yanlr_README_autotoc_md851}{}\doxysubsubsection{Arch Linux}\label{md_src_plugins_yanlr_README_autotoc_md851}
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{md_src_plugins_yanlr_README_autotoc_md852}{}\doxysubsubsection{Debian Linux}\label{md_src_plugins_yanlr_README_autotoc_md852}
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{md_src_plugins_yanlr_README_autotoc_md853}{}\doxysubsubsection{mac\+OS}\label{md_src_plugins_yanlr_README_autotoc_md853}
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{md_src_plugins_yanlr_README_autotoc_md854}{}\doxysubsection{Examples}\label{md_src_plugins_yanlr_README_autotoc_md854}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md855}{}\doxysubsubsection{Mappings}\label{md_src_plugins_yanlr_README_autotoc_md855}
\`{}\`{}{\ttfamily  @section autotoc\+\_\+md856 Mount plugin to}user/tests/yanlr\`{} sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{md_src_plugins_yanlr_README_autotoc_md857}{}\doxysection{Manually add some mappings to the configuration file}\label{md_src_plugins_yanlr_README_autotoc_md857}
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{md_src_plugins_yanlr_README_autotoc_md858}{}\doxysection{Store value at root of mountpoint}\label{md_src_plugins_yanlr_README_autotoc_md858}
kdb set user/tests/yanlr \textquotesingle{}Mount Eerie\textquotesingle{} kdb get user/tests/yanlr \#$>$ Mount Eerie\hypertarget{md_src_plugins_yanlr_README_autotoc_md859}{}\doxysection{Add new key-\/value pairs}\label{md_src_plugins_yanlr_README_autotoc_md859}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md860}{}\doxysection{Yan L\+R actually uses the Y\+A\+M\+L Smith plugin to write data}\label{md_src_plugins_yanlr_README_autotoc_md860}
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{md_src_plugins_yanlr_README_autotoc_md861}{}\doxysection{Undo modifications to the key database}\label{md_src_plugins_yanlr_README_autotoc_md861}
kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}{0}
\DoxyCodeLine{\#\#\# Arrays}
\end{DoxyCode}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md862}{}\doxysection{Mount plugin to $<$tt$>$/tests/yanlr$<$/tt$>$}\label{md_src_plugins_yanlr_README_autotoc_md862}
sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{md_src_plugins_yanlr_README_autotoc_md863}{}\doxysection{Manually add a sequences to the configuration file}\label{md_src_plugins_yanlr_README_autotoc_md863}
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{md_src_plugins_yanlr_README_autotoc_md864}{}\doxysection{Retrieve index of last array element}\label{md_src_plugins_yanlr_README_autotoc_md864}
kdb meta-\/get user/tests/yanlr/primes array \#$>$ \#3\hypertarget{md_src_plugins_yanlr_README_autotoc_md865}{}\doxysection{Undo modifications to the key database}\label{md_src_plugins_yanlr_README_autotoc_md865}
kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}{0}
\DoxyCodeLine{\#\#\# Boolean Values}
\end{DoxyCode}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md866}{}\doxysection{Mount plugin to $<$tt$>$/tests/yanlr$<$/tt$>$}\label{md_src_plugins_yanlr_README_autotoc_md866}
sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{md_src_plugins_yanlr_README_autotoc_md867}{}\doxysection{Manually add a boolean value to the database}\label{md_src_plugins_yanlr_README_autotoc_md867}
printf \textquotesingle{}boolean\+: true\textquotesingle{} $>$ {\ttfamily kdb file user/tests/yanlr}\hypertarget{md_src_plugins_yanlr_README_autotoc_md868}{}\doxysection{Elektra stores boolean values as $<$tt$>$0$<$/tt$>$ and $<$tt$>$1$<$/tt$>$}\label{md_src_plugins_yanlr_README_autotoc_md868}
kdb get user/tests/yanlr/boolean \#$>$ 1\hypertarget{md_src_plugins_yanlr_README_autotoc_md869}{}\doxysection{Undo modifications to the key database}\label{md_src_plugins_yanlr_README_autotoc_md869}
kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}{0}
\DoxyCodeLine{\#\#\# Null Values}
\end{DoxyCode}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md870}{}\doxysection{Mount plugin to $<$tt$>$/tests/yanlr$<$/tt$>$}\label{md_src_plugins_yanlr_README_autotoc_md870}
sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{md_src_plugins_yanlr_README_autotoc_md871}{}\doxysection{Manually add a null value to the database}\label{md_src_plugins_yanlr_README_autotoc_md871}
printf \textquotesingle{}\char`\"{}null\char`\"{}\+:\textquotesingle{} $>$ {\ttfamily kdb file user/tests/yanlr}\hypertarget{md_src_plugins_yanlr_README_autotoc_md872}{}\doxysection{Elektra adds the metakey $<$tt$>$binary$<$/tt$>$ for empty keys}\label{md_src_plugins_yanlr_README_autotoc_md872}
kdb meta-\/ls user/tests/yanlr/null \#$>$ binary\hypertarget{md_src_plugins_yanlr_README_autotoc_md873}{}\doxysection{Undo modifications to the key database}\label{md_src_plugins_yanlr_README_autotoc_md873}
kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}{0}
\DoxyCodeLine{\#\#\# Error Messages}
\end{DoxyCode}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md874}{}\doxysection{Mount plugin}\label{md_src_plugins_yanlr_README_autotoc_md874}
sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{md_src_plugins_yanlr_README_autotoc_md875}{}\doxysection{Manually add syntactically incorrect data}\label{md_src_plugins_yanlr_README_autotoc_md875}
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{md_src_plugins_yanlr_README_autotoc_md876}{}\doxysection{The plugin reports the location of the error}\label{md_src_plugins_yanlr_README_autotoc_md876}
kdb ls user/tests/yanlr \hypertarget{md_src_plugins_yanlr_README_autotoc_md877}{}\doxysection{R\+E\+T\+: 5}\label{md_src_plugins_yanlr_README_autotoc_md877}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md878}{}\doxysection{S\+T\+D\+E\+R\+R\+: .$\ast$/config.\+yaml\+:2\+:1\+: mismatched input \textquotesingle{}-\/ \textquotesingle{} expecting end of map.$\ast$}\label{md_src_plugins_yanlr_README_autotoc_md878}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md879}{}\doxysection{Let us look at the error message more closely.}\label{md_src_plugins_yanlr_README_autotoc_md879}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md880}{}\doxysection{Since the location of $<$tt$>$config.\+yaml$<$/tt$>$ depends on the current user and O\+S,}\label{md_src_plugins_yanlr_README_autotoc_md880}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md881}{}\doxysection{we store the text before $<$tt$>$config.\+yaml$<$/tt$>$ as $<$tt$>$user/tests/error/prefix$<$/tt$>$.}\label{md_src_plugins_yanlr_README_autotoc_md881}
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{md_src_plugins_yanlr_README_autotoc_md882}{}\doxysection{We also store the length of the prefix, so we can remove it from every}\label{md_src_plugins_yanlr_README_autotoc_md882}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md883}{}\doxysection{line of the error message.}\label{md_src_plugins_yanlr_README_autotoc_md883}
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{md_src_plugins_yanlr_README_autotoc_md884}{}\doxysection{Since we only want to look at the “reason” of the error, we}\label{md_src_plugins_yanlr_README_autotoc_md884}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md885}{}\doxysection{remove the other part of the error message with $<$tt$>$head$<$/tt$>$ and $<$tt$>$tail$<$/tt$>$.}\label{md_src_plugins_yanlr_README_autotoc_md885}
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{md_src_plugins_yanlr_README_autotoc_md886}{}\doxysection{Fix syntax error}\label{md_src_plugins_yanlr_README_autotoc_md886}
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{md_src_plugins_yanlr_README_autotoc_md887}{}\doxysection{Undo modifications}\label{md_src_plugins_yanlr_README_autotoc_md887}
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.\hypertarget{md_src_plugins_yanlr_README_autotoc_md888}{}\doxysubsubsection{Comments}\label{md_src_plugins_yanlr_README_autotoc_md888}
The \href{/home/mpranj/workspace/libelektra/src/plugins/yanlr/yaml_lexer.cpp}{\texttt{ lexer}} does currently tokenize comments. Consequently the plugin grammar of the plugin does also match comments. However, the \href{/home/mpranj/workspace/libelektra/src/plugins/yanlr/listener.cpp}{\texttt{ listener}} does currently {\bfseries{ignore comments}}.\hypertarget{md_src_plugins_yanlr_README_autotoc_md889}{}\doxysubsubsection{Indentation}\label{md_src_plugins_yanlr_README_autotoc_md889}
The lexer does not check for incorrect indentation. Consequently the following Y\+A\+ML data\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{value}
\end{DoxyCode}


will produce a plain scalar containing a tab character followed by the text {\ttfamily value}. The correct behavior would be to report an error, since Y\+A\+ML does not allow tab characters in indentation.\hypertarget{md_src_plugins_yanlr_README_autotoc_md890}{}\doxysubsubsection{Error Messages}\label{md_src_plugins_yanlr_README_autotoc_md890}
Visualized error messages (containing {\ttfamily $^\wedge$} markers) might not point to the correct error location, if the input contains tabs or unicode characters with a length other than {\ttfamily 1}. 