.TH "autotoc_md861" 3elektra "Tue Nov 26 2019" "Version 0.9.1" "Elektra" \" -*- nroff -*-
.ad l
.nh
.SH NAME
autotoc_md861 \- Plugin: yanlr
.IP "\(bu" 2
infos = Information about the yanlr plugin is in keys below
.IP "\(bu" 2
infos/author = René Schwaiger sanssecours@me.com
.IP "\(bu" 2
infos/licence = BSD
.IP "\(bu" 2
infos/needs = directoryvalue yamlsmith
.IP "\(bu" 2
infos/provides = storage/yaml
.IP "\(bu" 2
infos/recommends =
.IP "\(bu" 2
infos/placements = getstorage
.IP "\(bu" 2
infos/status = maintained unittest preview experimental unfinished nodoc concept discouraged
.IP "\(bu" 2
infos/metadata =
.IP "\(bu" 2
infos/description = This storage plugin use a parser generated by ANTLR to read YAML files
.PP
.SH "Yan LR"
.PP
.SS "Introduction"
This plugin uses ANTLR to generate a parser for the \fCYAML\fP serialization format\&. Apart from the hand written \fClexer\fP, all other parts of the plugin use standard ANTLR tools, such as
.PP
.IP "\(bu" 2
an ANTLR \fBparser grammar\fP,
.IP "\(bu" 2
a \fClistener\fP, that reacts to matches in the grammar building a key set, and
.IP "\(bu" 2
an \fCerror listener\fP that reacts to syntax errors
.PP
.SS "Dependencies"
The plugin requires
.PP
.IP "\(bu" 2
\fCANTLR\fP \fC4\&.6\fP or later, and
.IP "\(bu" 2
\fCANTLR 4’s C++ runtime\fP\&.
.PP
.PP
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 \fCat ANTLR’s homepage\fP and at the \fCReadMe of the ANTLR C++ runtime\fP\&.
.PP
Please note that we only tested the plugin with ANTLR \fC4\&.7\&.1\fP (and later versions of ANTLR)\&.
.SS "Arch Linux"
In \fCArch Linux\fP the required packages are called \fC\fCantlr4\fP\fP and \fC\fCantlr4-runtime\fP\fP\&.
.PP
.PP
.nf
pacman -Sy --noconfirm antlr4 antlr4-runtime
.fi
.PP
.SS "Debian Linux"
In Debian Linux you need the packages \fC\fCantlr4\fP\fP and \fC\fClibantlr4-runtime-dev\fP\fP\&.
.PP
.PP
.nf
apt-get -y install antlr4 libantlr4-runtime-dev
.fi
.PP
.SS "macOS"
To install the dependencies of the plugin using \fCHomebrew\fP, please use the command below\&.
.PP
.PP
.nf
brew install antlr antlr4-cpp-runtime
.fi
.PP
.SS "Examples"
.SS "Mappings"
``\fC @section autotoc_md869 Mount plugin to\fPuser/tests/yanlr` sudo kdb mount config\&.yaml user/tests/yanlr yanlr
.SH "Manually add some mappings to the configuration file"
.PP
printf 'all : circles presuppose
.br
' > \fCkdb file user/tests/yanlr\fP printf 'hello : world
.br
' >> \fCkdb file user/tests/yanlr\fP
.PP
kdb ls /tests/yanlr #> user/tests/yanlr/all #> user/tests/yanlr/hello
.PP
kdb get user/tests/yanlr/all #> circles presuppose
.SH "Store value at root of mountpoint"
.PP
kdb set user/tests/yanlr 'Mount Eerie' kdb get user/tests/yanlr #> Mount Eerie
.SH "Add new key-value pairs"
.PP
.SH "Yan LR actually uses the YAML Smith plugin to write data"
.PP
kdb set user/tests/yanlr/brand new kdb set user/tests/yanlr/brand/new eyes kdb set user/tests/yanlr/dance/gavin 'Dance!'
.PP
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
.PP
kdb get /tests/yanlr/hello #> world kdb get user/tests/yanlr/brand #> new kdb get /tests/yanlr/dance/gavin #> Dance!
.SH "Undo modifications to the key database"
.PP
kdb rm -r user/tests/yanlr sudo kdb umount user/tests/yanlr
.PP
.nf
### Arrays
.fi
.PP
.SH "Mount plugin to /tests/yanlr"
.PP
sudo kdb mount config\&.yaml user/tests/yanlr yanlr
.SH "Manually add a sequences to the configuration file"
.PP
printf 'primes:
.br
' > \fCkdb file user/tests/yanlr\fP printf ' - two
.br
' >> \fCkdb file user/tests/yanlr\fP printf ' - three
.br
' >> \fCkdb file user/tests/yanlr\fP printf ' - five
.br
' >> \fCkdb file user/tests/yanlr\fP
.PP
kdb ls user/tests/yanlr #> user/tests/yanlr/primes #> user/tests/yanlr/primes/#0 #> user/tests/yanlr/primes/#1 #> user/tests/yanlr/primes/#2
.PP
kdb set user/tests/yanlr/primes/#3 seven
.SH "Retrieve index of last array element"
.PP
kdb meta-get user/tests/yanlr/primes array #> #3
.SH "Undo modifications to the key database"
.PP
kdb rm -r user/tests/yanlr sudo kdb umount user/tests/yanlr
.PP
.nf
### Boolean Values
.fi
.PP
.SH "Mount plugin to /tests/yanlr"
.PP
sudo kdb mount config\&.yaml user/tests/yanlr yanlr
.SH "Manually add a boolean value to the database"
.PP
printf 'boolean: true' > \fCkdb file user/tests/yanlr\fP
.SH "Elektra stores boolean values as 0 and 1"
.PP
kdb get user/tests/yanlr/boolean #> 1
.SH "Undo modifications to the key database"
.PP
kdb rm -r user/tests/yanlr sudo kdb umount user/tests/yanlr
.PP
.nf
### Null Values
.fi
.PP
.SH "Mount plugin to /tests/yanlr"
.PP
sudo kdb mount config\&.yaml user/tests/yanlr yanlr
.SH "Manually add a null value to the database"
.PP
printf ''null':' > \fCkdb file user/tests/yanlr\fP
.SH "Elektra adds the metakey binary for empty keys"
.PP
kdb meta-ls user/tests/yanlr/null #> binary
.SH "Undo modifications to the key database"
.PP
kdb rm -r user/tests/yanlr sudo kdb umount user/tests/yanlr
.PP
.nf
### Error Messages
.fi
.PP
.SH "Mount plugin"
.PP
sudo kdb mount config\&.yaml user/tests/yanlr yanlr
.SH "Manually add syntactically incorrect data"
.PP
printf -- 'key: - element 1
.br
' > \fCkdb file user/tests/yanlr\fP printf -- '- element 2 # Incorrect Indentation!' >> \fCkdb file user/tests/yanlr\fP
.SH "The plugin reports the location of the error"
.PP
kdb ls user/tests/yanlr
.SH "RET: 5"
.PP
.SH "STDERR: \&.*/config\&.yaml:2:1: mismatched input '- ' expecting end of map\&.*"
.PP
.SH "Let us look at the error message more closely\&."
.PP
.SH "Since the location of config\&.yaml depends on the current user and OS,"
.PP
.SH "we store the text before config\&.yaml as user/tests/error/prefix\&."
.PP
kdb set user/tests/error '$(2>&1 kdb ls user/tests/yanlr)' kdb set user/tests/error/prefix '$(kdb get user/tests/error | grep 'config\&.yaml' | head -1 | sed -E 's/(\&.*)config\&.yaml\&.*/\\1/')'
.SH "We also store the length of the prefix, so we can remove it from every"
.PP
.SH "line of the error message\&."
.PP
kdb set user/tests/error/prefix/length '$(kdb get user/tests/error/prefix | wc -c | sed 's/[ ]*//g')'
.SH "Since we only want to look at the “reason” of the error, we"
.PP
.SH "remove the other part of the error message with head and tail\&."
.PP
kdb get user/tests/error | tail -n6 | cut -c'$(kdb get user/tests/error/prefix/length | tr -d '\\n')'- #> config\&.yaml:2:1: mismatched input '- ' expecting end of map #> - element 2 # Incorrect Indentation! #> ^^ #> config\&.yaml:2:37: extraneous input 'end of map' expecting end of document #> - element 2 # Incorrect Indentation! #> ^
.SH "Fix syntax error"
.PP
printf -- 'key: - element 1
.br
' > \fCkdb file user/tests/yanlr\fP printf -- ' - element 2 # Fixed!' >> \fCkdb file user/tests/yanlr\fP
.PP
kdb ls user/tests/yanlr #> user/tests/yanlr/key #> user/tests/yanlr/key/#0 #> user/tests/yanlr/key/#1
.SH "Undo modifications"
.PP
kdb rm -r user/tests/error kdb rm -r user/tests/yanlr sudo kdb umount user/tests/yanlr
.PP
.nf
## Limitations
- The plugin does **not support**
- plain scalars that span **multiple lines**,
- **special characters** inside double quoted scalars,
- other **line endings** than `\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\&.
### Input Restrictions
The plugin should, but does not, limit the amount
- of **nesting levels**,
- the **length of numbers**, and
- the **length of scalars**
\&. These restrictions would make it less easy to crash the parser, by feeding it unrestricted data\&.
### Duplicate Keys
Currently the plugin parses the input
```yaml
duplicate: one
duplicate: two
.fi
.PP
.PP
storing the value \fCtwo\fP\&. According to the YAML specification the parser should not allow duplicated keys, and instead fail with an error, for the input above\&.