
\begin{DoxyItemize}
\item infos = Information about the yanlr plugin is in keys below
\item infos/author = René Schwaiger \href{mailto:sanssecours@me.com}{\tt 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_md871_src_plugins_yanlr_README_md}{}\section{Yan LR}\label{autotoc_md871_src_plugins_yanlr_README_md}
\hypertarget{autotoc_md871_autotoc_md872}{}\subsection{Introduction}\label{autotoc_md871_autotoc_md872}
This plugin uses A\+N\+T\+LR to generate a parser for the \href{http://yaml.org}{\tt Y\+A\+ML} serialization format. Apart from the hand written \href{/home/jenkins/workspace/libelektra_master-Q2SIBK3KE2NBEMJ4WVGJXAXCSCB77DUBUULVLZDKHQEV3WNDXBMA/src/plugins/yanlr/yaml_lexer.cpp}{\tt 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/jenkins/workspace/libelektra_master-Q2SIBK3KE2NBEMJ4WVGJXAXCSCB77DUBUULVLZDKHQEV3WNDXBMA/src/plugins/yanlr/listener.cpp}{\tt listener}, that reacts to matches in the grammar building a key set, and
\item an \href{/home/jenkins/workspace/libelektra_master-Q2SIBK3KE2NBEMJ4WVGJXAXCSCB77DUBUULVLZDKHQEV3WNDXBMA/src/plugins/yanlr/error_listener.cpp}{\tt error listener} that reacts to syntax errors
\end{DoxyItemize}\hypertarget{autotoc_md871_autotoc_md873}{}\subsection{Dependencies}\label{autotoc_md871_autotoc_md873}
The plugin requires


\begin{DoxyItemize}
\item \href{https://www.antlr.org}{\tt A\+N\+T\+LR} {\ttfamily 4.\+6} or later (\href{https://repology.org/metapackage/antlr4}{\tt {\ttfamily antlr4}}), and
\item \href{https://github.com/antlr/antlr4/tree/master/runtime/Cpp}{\tt A\+N\+T\+LR 4’s C++ runtime} (\href{https://repology.org/metapackage/antlr4-cpp-runtime}{\tt {\ttfamily antlr4-\/cpp-\/runtime}} or \href{https://packages.debian.org/search?searchon=names&keywords=libantlr4-runtime-dev}{\tt {\ttfamily libantlr4-\/runtime-\/dev}})
\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}{\tt at A\+N\+T\+L\+R’s homepage} and at the \href{https://github.com/antlr/antlr4/tree/master/runtime/Cpp}{\tt 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_md871_autotoc_md874}{}\subsection{Examples}\label{autotoc_md871_autotoc_md874}
\hypertarget{autotoc_md871_autotoc_md875}{}\subsubsection{Mappings}\label{autotoc_md871_autotoc_md875}
``{\ttfamily  @section autotoc\+\_\+md876 Mount plugin to}user/tests/yanlr` sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{autotoc_md871_autotoc_md877}{}\section{Manually add some mappings to the configuration file}\label{autotoc_md871_autotoc_md877}
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_md871_autotoc_md878}{}\section{Store value at root of mountpoint}\label{autotoc_md871_autotoc_md878}
kdb set user/tests/yanlr \textquotesingle{}Mount Eerie\textquotesingle{} kdb get user/tests/yanlr \#$>$ Mount Eerie\hypertarget{autotoc_md871_autotoc_md879}{}\section{Add new key-\/value pairs}\label{autotoc_md871_autotoc_md879}
\hypertarget{autotoc_md871_autotoc_md880}{}\section{Yan L\+R actually uses the Y\+A\+M\+L Smith plugin to write data}\label{autotoc_md871_autotoc_md880}
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_md871_autotoc_md881}{}\section{Undo modifications to the key database}\label{autotoc_md871_autotoc_md881}
kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}
### Arrays
\end{DoxyCode}
 \hypertarget{autotoc_md871_autotoc_md882}{}\section{Mount plugin to `/tests/yanlr`}\label{autotoc_md871_autotoc_md882}
sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{autotoc_md871_autotoc_md883}{}\section{Manually add a sequences to the configuration file}\label{autotoc_md871_autotoc_md883}
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_md871_autotoc_md884}{}\section{Retrieve index of last array element}\label{autotoc_md871_autotoc_md884}
kdb getmeta user/tests/yanlr/primes array \#$>$ \#3\hypertarget{autotoc_md871_autotoc_md885}{}\section{Undo modifications to the key database}\label{autotoc_md871_autotoc_md885}
kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}
### Boolean Values
\end{DoxyCode}
 \hypertarget{autotoc_md871_autotoc_md886}{}\section{Mount plugin to `/tests/yanlr`}\label{autotoc_md871_autotoc_md886}
sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{autotoc_md871_autotoc_md887}{}\section{Manually add a boolean value to the database}\label{autotoc_md871_autotoc_md887}
printf \textquotesingle{}boolean\+: true\textquotesingle{} $>$ {\ttfamily kdb file user/tests/yanlr}\hypertarget{autotoc_md871_autotoc_md888}{}\section{Elektra stores boolean values as `0` and `1`}\label{autotoc_md871_autotoc_md888}
kdb get user/tests/yanlr/boolean \#$>$ 1\hypertarget{autotoc_md871_autotoc_md889}{}\section{Undo modifications to the key database}\label{autotoc_md871_autotoc_md889}
kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}
### Null Values
\end{DoxyCode}
 \hypertarget{autotoc_md871_autotoc_md890}{}\section{Mount plugin to `/tests/yanlr`}\label{autotoc_md871_autotoc_md890}
sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{autotoc_md871_autotoc_md891}{}\section{Manually add a null value to the database}\label{autotoc_md871_autotoc_md891}
printf \textquotesingle{}\char`\"{}null\char`\"{}\+:\textquotesingle{} $>$ {\ttfamily kdb file user/tests/yanlr}\hypertarget{autotoc_md871_autotoc_md892}{}\section{Elektra adds the metakey `binary` for empty keys}\label{autotoc_md871_autotoc_md892}
kdb lsmeta user/tests/yanlr/null \#$>$ binary\hypertarget{autotoc_md871_autotoc_md893}{}\section{Undo modifications to the key database}\label{autotoc_md871_autotoc_md893}
kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}
### Error Messages
\end{DoxyCode}
 \hypertarget{autotoc_md871_autotoc_md894}{}\section{Mount plugin}\label{autotoc_md871_autotoc_md894}
sudo kdb mount config.\+yaml user/tests/yanlr yanlr\hypertarget{autotoc_md871_autotoc_md895}{}\section{Manually add syntactically incorrect data}\label{autotoc_md871_autotoc_md895}
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_md871_autotoc_md896}{}\section{The plugin reports the location of the error}\label{autotoc_md871_autotoc_md896}
kdb ls user/tests/yanlr \hypertarget{autotoc_md871_autotoc_md897}{}\section{R\+E\+T\+: 5}\label{autotoc_md871_autotoc_md897}
\hypertarget{autotoc_md871_autotoc_md898}{}\section{S\+T\+D\+E\+R\+R\+: .$\ast$/config.\+yaml\+:2\+:1\+: mismatched input \textquotesingle{}-\/ \textquotesingle{} expecting end of map.$\ast$}\label{autotoc_md871_autotoc_md898}
\hypertarget{autotoc_md871_autotoc_md899}{}\section{Let us look at the error message more closely.}\label{autotoc_md871_autotoc_md899}
\hypertarget{autotoc_md871_autotoc_md900}{}\section{Since the location of `config.\+yaml` depends on the current user and O\+S,}\label{autotoc_md871_autotoc_md900}
\hypertarget{autotoc_md871_autotoc_md901}{}\section{we store the text before `config.\+yaml` as `user/tests/error/prefix`.}\label{autotoc_md871_autotoc_md901}
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_md871_autotoc_md902}{}\section{We also store the length of the prefix, so we can remove it from every}\label{autotoc_md871_autotoc_md902}
\hypertarget{autotoc_md871_autotoc_md903}{}\section{line of the error message.}\label{autotoc_md871_autotoc_md903}
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_md871_autotoc_md904}{}\section{Since we only want to look at the “reason” of the error, we}\label{autotoc_md871_autotoc_md904}
\hypertarget{autotoc_md871_autotoc_md905}{}\section{remove the other part of the error message with `head` and `tail`.}\label{autotoc_md871_autotoc_md905}
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_md871_autotoc_md906}{}\section{Fix syntax error}\label{autotoc_md871_autotoc_md906}
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_md871_autotoc_md907}{}\section{Undo modifications}\label{autotoc_md871_autotoc_md907}
kdb rm -\/r user/tests/error kdb rm -\/r user/tests/yanlr sudo kdb umount user/tests/yanlr 
\begin{DoxyCode}
## Limitations

- The plugin does **not support**

  - plain scalars that span **multiple lines**,
  - **special characters** inside double quoted scalars,
  - other **line endings** than `\(\backslash\)n` (Unix line endings),
  - **block scalars**,
  - **flow collections**,
  - **tags**,
  - **anchors & aliases**,
  - **multiple documents**, and
  - document **start and end markers**

  .

- Yan LR does not provide write support for data. Please use the [YAML Smith](@ref
       src\_plugins\_yamlsmith\_README\_md) plugin for that purpose.

### Comments

The
       [lexer](/home/jenkins/workspace/libelektra\_master-Q2SIBK3KE2NBEMJ4WVGJXAXCSCB77DUBUULVLZDKHQEV3WNDXBMA/src/plugins/yanlr/yaml\_lexer.cpp) does currently tokenize comments. Consequently the [plugin grammar](@ref
       src\_plugins\_yanlr\_YAML\_g4) of the plugin does also match comments. However, the
       [listener](/home/jenkins/workspace/libelektra\_master-Q2SIBK3KE2NBEMJ4WVGJXAXCSCB77DUBUULVLZDKHQEV3WNDXBMA/src/plugins/yanlr/listener.cpp)
       does currently **ignore comments**.

### Indentation

The lexer does not check for incorrect indentation. Consequently the following YAML data:



```yaml
        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.