
\begin{DoxyItemize}
\item infos = Information about the yanlr plugin is in keys below
\end{DoxyItemize}

infos/author = René Schwaiger \href{mailto:sanssecours@me.com}{\texttt{ sanssecours@me.\+com}}
\begin{DoxyItemize}
\item infos/licence = BSD
\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 ANTLR to read YAML files
\end{DoxyItemize}\hypertarget{md_src_plugins_yanlr_README_autotoc_md574}{}\doxysection{Yan LR}\label{md_src_plugins_yanlr_README_autotoc_md574}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md575}{}\doxysubsection{Introduction}\label{md_src_plugins_yanlr_README_autotoc_md575}
This plugin uses ANTLR to generate a parser for the \href{http://yaml.org}{\texttt{ YAML}} serialization format. Apart from the hand written \href{yaml_lexer.cpp}{\texttt{ lexer}}, all other parts of the plugin use standard ANTLR tools, such as


\begin{DoxyItemize}
\item an ANTLR \href{YAML.g4}{\texttt{ parser grammar}},
\item a \href{listener.cpp}{\texttt{ listener}}, that reacts to matches in the grammar building a key set, and
\item an \href{error_listener.cpp}{\texttt{ error listener}} that reacts to syntax errors
\end{DoxyItemize}\hypertarget{md_src_plugins_yanlr_README_autotoc_md576}{}\doxysubsection{Dependencies}\label{md_src_plugins_yanlr_README_autotoc_md576}
The plugin requires


\begin{DoxyItemize}
\item \href{https://www.antlr.org}{\texttt{ ANTLR}} {\ttfamily 4.\+6} or later, and
\item \href{https://github.com/antlr/antlr4/tree/master/runtime/Cpp}{\texttt{ ANTLR 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 ANTLR’s homepage}} and at the \href{https://github.com/antlr/antlr4/tree/master/runtime/Cpp}{\texttt{ Read\+Me of the ANTLR C++ runtime}}.

Please note that we only tested the plugin with ANTLR {\ttfamily 4.\+7.\+1} (and later versions of ANTLR).\hypertarget{md_src_plugins_yanlr_README_autotoc_md577}{}\doxysubsubsection{Arch Linux}\label{md_src_plugins_yanlr_README_autotoc_md577}
In \href{https://www.archlinux.org/}{\texttt{ Arch Linux}} the required packages are called \href{https://archlinux.org/packages/community/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_md578}{}\doxysubsubsection{Debian Linux}\label{md_src_plugins_yanlr_README_autotoc_md578}
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_md579}{}\doxysubsubsection{mac\+OS}\label{md_src_plugins_yanlr_README_autotoc_md579}
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_md580}{}\doxysubsection{Examples}\label{md_src_plugins_yanlr_README_autotoc_md580}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md581}{}\doxysubsubsection{Mappings}\label{md_src_plugins_yanlr_README_autotoc_md581}

\begin{DoxyCode}{0}
\DoxyCodeLine{\# Mount plugin to `user:/tests/yanlr`}
\DoxyCodeLine{sudo kdb mount config.yaml user:/tests/yanlr yanlr}
\DoxyCodeLine{}
\DoxyCodeLine{\# Manually add some mappings to the configuration file}
\DoxyCodeLine{printf 'all : circles presuppose\(\backslash\)n' >  `kdb file user:/tests/yanlr`}
\DoxyCodeLine{printf 'hello : world\(\backslash\)n'            >> `kdb file user:/tests/yanlr`}
\DoxyCodeLine{}
\DoxyCodeLine{kdb ls /tests/yanlr}
\DoxyCodeLine{\#> user:/tests/yanlr/all}
\DoxyCodeLine{\#> user:/tests/yanlr/hello}
\DoxyCodeLine{}
\DoxyCodeLine{kdb get user:/tests/yanlr/all}
\DoxyCodeLine{\#> circles presuppose}
\DoxyCodeLine{}
\DoxyCodeLine{\# Store value at root of mountpoint}
\DoxyCodeLine{kdb set user:/tests/yanlr 'Mount Eerie'}
\DoxyCodeLine{kdb get user:/tests/yanlr}
\DoxyCodeLine{\#> Mount Eerie}
\DoxyCodeLine{}
\DoxyCodeLine{\# Add new key-\/value pairs}
\DoxyCodeLine{\# Yan LR actually uses the YAML Smith plugin to write data}
\DoxyCodeLine{kdb set user:/tests/yanlr/brand new}
\DoxyCodeLine{kdb set user:/tests/yanlr/brand/new eyes}
\DoxyCodeLine{kdb set user:/tests/yanlr/dance/gavin 'Dance!'}
\DoxyCodeLine{}
\DoxyCodeLine{kdb ls /tests/yanlr}
\DoxyCodeLine{\#> user:/tests/yanlr}
\DoxyCodeLine{\#> user:/tests/yanlr/all}
\DoxyCodeLine{\#> user:/tests/yanlr/brand}
\DoxyCodeLine{\#> user:/tests/yanlr/brand/new}
\DoxyCodeLine{\#> user:/tests/yanlr/dance/gavin}
\DoxyCodeLine{\#> user:/tests/yanlr/hello}
\DoxyCodeLine{}
\DoxyCodeLine{kdb get /tests/yanlr/hello}
\DoxyCodeLine{\#> world}
\DoxyCodeLine{kdb get user:/tests/yanlr/brand}
\DoxyCodeLine{\#> new}
\DoxyCodeLine{kdb get /tests/yanlr/dance/gavin}
\DoxyCodeLine{\#> Dance!}
\DoxyCodeLine{}
\DoxyCodeLine{\# Undo modifications to the key database}
\DoxyCodeLine{kdb rm -\/r user:/tests/yanlr}
\DoxyCodeLine{sudo kdb umount user:/tests/yanlr}

\end{DoxyCode}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md582}{}\doxysubsubsection{Arrays}\label{md_src_plugins_yanlr_README_autotoc_md582}

\begin{DoxyCode}{0}
\DoxyCodeLine{\# Mount plugin to `/tests/yanlr`}
\DoxyCodeLine{sudo kdb mount config.yaml user:/tests/yanlr yanlr}
\DoxyCodeLine{}
\DoxyCodeLine{\# Manually add a sequences to the configuration file}
\DoxyCodeLine{printf 'primes:\(\backslash\)n'   >  `kdb file user:/tests/yanlr`}
\DoxyCodeLine{printf '  -\/ two\(\backslash\)n'   >> `kdb file user:/tests/yanlr`}
\DoxyCodeLine{printf '  -\/ three\(\backslash\)n' >> `kdb file user:/tests/yanlr`}
\DoxyCodeLine{printf '  -\/ five\(\backslash\)n'  >> `kdb file user:/tests/yanlr`}
\DoxyCodeLine{}
\DoxyCodeLine{kdb ls user:/tests/yanlr}
\DoxyCodeLine{\#> user:/tests/yanlr/primes}
\DoxyCodeLine{\#> user:/tests/yanlr/primes/\#0}
\DoxyCodeLine{\#> user:/tests/yanlr/primes/\#1}
\DoxyCodeLine{\#> user:/tests/yanlr/primes/\#2}
\DoxyCodeLine{}
\DoxyCodeLine{kdb set user:/tests/yanlr/primes/\#3 seven}
\DoxyCodeLine{}
\DoxyCodeLine{\# Retrieve index of last array element}
\DoxyCodeLine{kdb meta-\/get user:/tests/yanlr/primes array}
\DoxyCodeLine{\#> \#3}
\DoxyCodeLine{}
\DoxyCodeLine{\# Undo modifications to the key database}
\DoxyCodeLine{kdb rm -\/r user:/tests/yanlr}
\DoxyCodeLine{sudo kdb umount user:/tests/yanlr}

\end{DoxyCode}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md583}{}\doxysubsubsection{Boolean Values}\label{md_src_plugins_yanlr_README_autotoc_md583}

\begin{DoxyCode}{0}
\DoxyCodeLine{\# Mount plugin to `/tests/yanlr`}
\DoxyCodeLine{sudo kdb mount config.yaml user:/tests/yanlr yanlr}
\DoxyCodeLine{}
\DoxyCodeLine{\# Manually add a boolean value to the database}
\DoxyCodeLine{printf 'boolean: true' > `kdb file user:/tests/yanlr`}
\DoxyCodeLine{}
\DoxyCodeLine{\# Elektra stores boolean values as `0` and `1`}
\DoxyCodeLine{kdb get user:/tests/yanlr/boolean}
\DoxyCodeLine{\#> 1}
\DoxyCodeLine{}
\DoxyCodeLine{\# Undo modifications to the key database}
\DoxyCodeLine{kdb rm -\/r user:/tests/yanlr}
\DoxyCodeLine{sudo kdb umount user:/tests/yanlr}

\end{DoxyCode}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md584}{}\doxysubsubsection{Null Values}\label{md_src_plugins_yanlr_README_autotoc_md584}

\begin{DoxyCode}{0}
\DoxyCodeLine{\# Mount plugin to `/tests/yanlr`}
\DoxyCodeLine{sudo kdb mount config.yaml user:/tests/yanlr yanlr}
\DoxyCodeLine{}
\DoxyCodeLine{\# Manually add a null value to the database}
\DoxyCodeLine{printf '"{}null"{}:' > `kdb file user:/tests/yanlr`}
\DoxyCodeLine{}
\DoxyCodeLine{\# Elektra adds the metakey `binary` for empty keys}
\DoxyCodeLine{kdb meta-\/ls user:/tests/yanlr/null}
\DoxyCodeLine{\#> binary}
\DoxyCodeLine{}
\DoxyCodeLine{\# Undo modifications to the key database}
\DoxyCodeLine{kdb rm -\/r user:/tests/yanlr}
\DoxyCodeLine{sudo kdb umount user:/tests/yanlr}

\end{DoxyCode}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md585}{}\doxysubsubsection{Error Messages}\label{md_src_plugins_yanlr_README_autotoc_md585}

\begin{DoxyCode}{0}
\DoxyCodeLine{\# Mount plugin}
\DoxyCodeLine{sudo kdb mount config.yaml user:/tests/yanlr yanlr}
\DoxyCodeLine{}
\DoxyCodeLine{\# Manually add syntactically incorrect data}
\DoxyCodeLine{printf -\/-\/ 'key: -\/ element 1\(\backslash\)n'                   >  `kdb file user:/tests/yanlr`}
\DoxyCodeLine{printf -\/-\/ '-\/ element 2 \# Incorrect Indentation!' >> `kdb file user:/tests/yanlr`}
\DoxyCodeLine{}
\DoxyCodeLine{\# The plugin reports the location of the error}
\DoxyCodeLine{kdb ls user:/tests/yanlr}
\DoxyCodeLine{\# RET: 5}
\DoxyCodeLine{\# STDERR: .*/config.yaml:2:1: mismatched input '-\/ ' expecting end of map.*}
\DoxyCodeLine{}
\DoxyCodeLine{\# Let us look at the error message more closely.}
\DoxyCodeLine{\# Since the location of `config.yaml` depends on the current user and OS,}
\DoxyCodeLine{\# we store the text before `config.yaml` as `user:/tests/error/prefix`.}
\DoxyCodeLine{kdb set user:/tests/error "{}\$(2>\&1 kdb ls user:/tests/yanlr)"{}}
\DoxyCodeLine{kdb set user:/tests/error/prefix "{}\$(kdb get user:/tests/error | grep 'config.yaml' | head -\/1 | sed -\/E 's/(.*)config.yaml.*/\(\backslash\)1/')"{}}
\DoxyCodeLine{\# We also store the length of the prefix, so we can remove it from every}
\DoxyCodeLine{\# line of the error message.}
\DoxyCodeLine{kdb set user:/tests/error/prefix/length "{}\$(kdb get user:/tests/error/prefix | wc -\/c | sed 's/[ ]*//g')"{}}
\DoxyCodeLine{}
\DoxyCodeLine{\# Since we only want to look at the “reason” of the error, we}
\DoxyCodeLine{\# remove the other part of the error message with `head` and `tail`.}
\DoxyCodeLine{kdb get user:/tests/error | tail -\/n6 | cut -\/c"{}\$(kdb get user:/tests/error/prefix/length | tr -\/d '\(\backslash\)n')"{}-\/}
\DoxyCodeLine{\#> config.yaml:2:1: mismatched input '-\/ ' expecting end of map}
\DoxyCodeLine{\#>                  -\/ element 2 \# Incorrect Indentation!}
\DoxyCodeLine{\#>                  \string^\string^}
\DoxyCodeLine{\#> config.yaml:2:37: extraneous input 'end of map' expecting end of document}
\DoxyCodeLine{\#>                   -\/ element 2 \# Incorrect Indentation!}
\DoxyCodeLine{\#>                                                       \string^}
\DoxyCodeLine{}
\DoxyCodeLine{\# Fix syntax error}
\DoxyCodeLine{printf -\/-\/ 'key: -\/ element 1\(\backslash\)n'        >  `kdb file user:/tests/yanlr`}
\DoxyCodeLine{printf -\/-\/ '     -\/ element 2 \# Fixed!' >> `kdb file user:/tests/yanlr`}
\DoxyCodeLine{}
\DoxyCodeLine{kdb ls user:/tests/yanlr}
\DoxyCodeLine{\#> user:/tests/yanlr/key}
\DoxyCodeLine{\#> user:/tests/yanlr/key/\#0}
\DoxyCodeLine{\#> user:/tests/yanlr/key/\#1}
\DoxyCodeLine{}
\DoxyCodeLine{\# Undo modifications}
\DoxyCodeLine{kdb rm -\/r user:/tests/error}
\DoxyCodeLine{kdb rm -\/r user:/tests/yanlr}
\DoxyCodeLine{sudo kdb umount user:/tests/yanlr}

\end{DoxyCode}
\hypertarget{md_src_plugins_yanlr_README_autotoc_md586}{}\doxysubsection{Limitations}\label{md_src_plugins_yanlr_README_autotoc_md586}

\begin{DoxyItemize}
\item The plugin does {\bfseries{not support}}
\begin{DoxyItemize}
\item plain scalars that span {\bfseries{multiple lines}},
\item {\bfseries{special characters}} inside double quoted scalars,
\item other {\bfseries{line endings}} than {\ttfamily \textbackslash{}n} (Unix line endings),
\item {\bfseries{block scalars}},
\item {\bfseries{flow collections}},
\item {\bfseries{tags}},
\item {\bfseries{anchors \& aliases}},
\item {\bfseries{multiple documents}}, and
\item document {\bfseries{start and end markers}}
\end{DoxyItemize}
\item Yan LR does not provide write support for data. Please use the \href{../yamlsmith/}{\texttt{ YAML Smith}} plugin for that purpose.
\end{DoxyItemize}\hypertarget{md_src_plugins_yanlr_README_autotoc_md587}{}\doxysubsubsection{Input Restrictions}\label{md_src_plugins_yanlr_README_autotoc_md587}
The plugin should, but does not, limit the amount


\begin{DoxyItemize}
\item of {\bfseries{nesting levels}},
\item the {\bfseries{length of numbers}}, and
\item the {\bfseries{length of scalars}}
\end{DoxyItemize}

. These restrictions would make it less easy to crash the parser, by feeding it unrestricted data.\hypertarget{md_src_plugins_yanlr_README_autotoc_md588}{}\doxysubsubsection{Duplicate Keys}\label{md_src_plugins_yanlr_README_autotoc_md588}
Currently the plugin parses the input


\begin{DoxyCode}{0}
\DoxyCodeLine{duplicate: one}
\DoxyCodeLine{duplicate: two}

\end{DoxyCode}


storing the value {\ttfamily two}. According to the YAML 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_md589}{}\doxysubsubsection{Comments}\label{md_src_plugins_yanlr_README_autotoc_md589}
The \href{yaml_lexer.cpp}{\texttt{ lexer}} does currently tokenize comments. Consequently the \href{YAML.g4}{\texttt{ plugin grammar}} of the plugin does also match comments. However, the \href{listener.cpp}{\texttt{ listener}} does currently {\bfseries{ignore comments}}.\hypertarget{md_src_plugins_yanlr_README_autotoc_md590}{}\doxysubsubsection{Indentation}\label{md_src_plugins_yanlr_README_autotoc_md590}
The lexer does not check for incorrect indentation. Consequently the following YAML 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 YAML does not allow tab characters in indentation.\hypertarget{md_src_plugins_yanlr_README_autotoc_md591}{}\doxysubsubsection{Error Messages}\label{md_src_plugins_yanlr_README_autotoc_md591}
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}. 