YAMBi: YAML Plugin Based on Parser Generated by Bison

.travis.yml

@@ -43,6 +43,7 @@ matrix:
         # [timeout]: https://docs.travis-ci.com/user/customizing-the-build/#build-timeouts
         - TOOLS=kdb
         - BINDINGS=cpp
+        - PLUGINS='ALL;-camel;-directoryvalue;-mini;-yambi;-yamlcpp;-yanlr'
         - TEST_COMMAND="ctest --output-on-failure -E 'testscr_check_(bashisms|doc|formatting|meta|oclint|plugins)'"
 
     - os: linux
@@ -188,6 +189,7 @@ before_install:
         # Unfortunately Xerces 3.2 causes multiple problems if we translate Elektra with GCC on macOS
         brew install xerces-c
       fi
+      brew install bison
       brew install dbus
       brew install discount
       brew install gpgme

doc/man/man7/elektra-plugins.7

@@ -198,6 +198,9 @@ yamlcpp \fIyamlcpp/\fR reads and writes data in the YAML \fIhttp://www\.yaml\.or
 yanlr \fIyanlr/\fR reads data using a parser generated by ANTLR \fIhttp://www\.antlr\.org\fR
 .
 .IP "\(bu" 4
+yambi \fIyambi/\fR reads data using a parser generated by Bison \fIhttps://www\.gnu\.org/software/bison\fR
+.
+.IP "\(bu" 4
 mmapstorage \fImmapstorage/\fR uses binary, not portable memory mapped file for a high performance storage
 .
 .IP "" 0

doc/news/_preparation_next_release.md

@@ -93,12 +93,9 @@ The following section lists news about the [modules](https://www.libelektra.org/
 
 - The `gpgme` plugin was brought into existence to provide cryptographic functions using GnuGP via the `libgpgme` library. See [#896] *(Peter Nirschl)*
 
+### YAMBi
 
-### <<Plugin1>>
-
-- <<TODO>>
-- <<TODO>>
-- <<TODO>>
+This new plugin parses a subset of YAML using a parser generated by [Bison](https://www.gnu.org/software/bison). *(René Schwaiger)*
 
 ### <<Plugin2>>
 

src/plugins/README.md

@@ -118,6 +118,7 @@ productive use:
 - [camel](camel/) reads and writes a very limited subset of [YAML][]
 - [yamlcpp](yamlcpp/) reads and writes data in the [YAML][] format using [yaml-cpp](https://github.com/jbeder/yaml-cpp)
 - [yanlr](yanlr/) reads data using a parser generated by [ANTLR](http://www.antlr.org)
+- [yambi](yambi/) reads data using a parser generated by [Bison](https://www.gnu.org/software/bison)
 - [mmapstorage](mmapstorage/) uses binary, not portable memory mapped file for a high performance storage
 
 [YAML]: http://www.yaml.org

src/plugins/cpptemplate/cpptemplate.hpp

@@ -19,9 +19,9 @@ using ckdb::Plugin;
 extern "C" {
 int elektraCppTemplateOpen (Plugin * handle, Key * errorKey);
 int elektraCppTemplateClose (Plugin * handle, Key * errorKey);
-int elektraCppTemplateGet (Plugin * handle, KeySet * ks, Key * parentKey);
-int elektraCppTemplateSet (Plugin * handle, KeySet * ks, Key * parentKey);
-int elektraCppTemplateError (Plugin * handle, KeySet * ks, Key * parentKey);
+int elektraCppTemplateGet (Plugin * handle, KeySet * returned, Key * parentKey);
+int elektraCppTemplateSet (Plugin * handle, KeySet * returned, Key * parentKey);
+int elektraCppTemplateError (Plugin * handle, KeySet * conf, Key * parentKey);
 int elektraCppTemplateCheckConfig (Key * errorKey, KeySet * conf);
 
 Plugin * ELEKTRA_PLUGIN_EXPORT (cpptemplate);

src/plugins/csvstorage/CMakeLists.txt

@@ -7,4 +7,5 @@ add_plugin (csvstorage
 			 elektra-proposal
 	    ADD_TEST
 	    INSTALL_TEST_DATA
-	    TEST_README)
+	    TEST_README
+	    TEST_REQUIRED_PLUGINS directoryvalue)

src/plugins/rename/CMakeLists.txt

@@ -3,4 +3,4 @@ add_plugin (rename
 		    rename.c
 	    ADD_TEST
 	    TEST_README
-	    TEST_REQUIRED_PLUGINS ni)
+	    TEST_REQUIRED_PLUGINS mini)

src/plugins/yajl/CMakeLists.txt

@@ -19,6 +19,7 @@ add_plugin (yajl
 		    "${CMAKE_CURRENT_BINARY_DIR}/yajl.h"
 	    ADD_TEST
 	    TEST_README
+	    TEST_REQUIRED_PLUGINS directoryvalue
 	    INSTALL_TEST_DATA
 	    INCLUDE_DIRECTORIES "${INCL}"
 	    LINK_ELEKTRA elektra-ease

src/plugins/yambi/CMakeLists.txt

@@ -0,0 +1,94 @@
+include (LibAddMacros)
+
+# ~~~
+# This functions checks if the dependencies for the YAMBi plugin are available.
+#
+# If they are, the function sets the variable `FOUND_DEPENDENCIES` to `TRUE`. The function then also sets:
+#
+# - BISON_YAMBI_OUTPUT_SOURCE to the path of the source files generated by Bison, and
+# - BISON_YAMBI_OUTPUT_HEADER to the path of the header files generated by Bison
+#
+# . If the function was unsuccessful it sets `FOUND_DEPENDENCIES` to `FALSE` and stores the reason for the failure in the variable
+# `FAILURE_MESSAGE`.
+# ~~~
+function (check_dependencies)
+	set (FOUND_DEPENDENCIES FALSE PARENT_SCOPE)
+
+	include (CheckIncludeFileCXX)
+	set (CMAKE_REQUIRED_QUIET ON)
+	check_include_file_cxx (codecvt HAVE_CODECVT)
+	if (NOT HAVE_CODECVT)
+		set (FAILURE_MESSAGE "because the current C++ library does not provide header file `codecvt`" PARENT_SCOPE)
+		return ()
+	endif (NOT HAVE_CODECVT)
+
+	if (APPLE)
+		# Add path to Homebrew version of Bison
+		list (APPEND CMAKE_PREFIX_PATH
+			     "/usr/local/opt/bison")
+	endif (APPLE)
+	find_package (BISON 3 QUIET)
+
+	if (NOT BISON_FOUND)
+		set (FAILURE_MESSAGE "Bison 3 (bison) not found" PARENT_SCOPE)
+		return ()
+	endif (NOT BISON_FOUND)
+
+	if (BISON_VERSION VERSION_LESS 3)
+		set (FAILURE_MESSAGE "Bison version 3 or later required (found version ${BISON_VERSION})" PARENT_SCOPE)
+		return ()
+	endif (BISON_VERSION VERSION_LESS 3)
+
+	bison_target (YAMBI ${CMAKE_CURRENT_SOURCE_DIR}/parser.ypp ${CMAKE_CURRENT_BINARY_DIR}/parser.cpp)
+
+	if (NOT BISON_YAMBI_DEFINED)
+		set (FAILURE_MESSAGE "generating the parser code failed" PARENT_SCOPE)
+		return ()
+	endif (NOT BISON_YAMBI_DEFINED)
+
+	set (BISON_YAMBI_OUTPUT_SOURCE ${BISON_YAMBI_OUTPUT_SOURCE} PARENT_SCOPE)
+	set (BISON_YAMBI_OUTPUT_HEADER ${BISON_YAMBI_OUTPUT_HEADER} PARENT_SCOPE)
+
+	set (FOUND_DEPENDENCIES TRUE PARENT_SCOPE)
+endfunction (check_dependencies)
+
+if (DEPENDENCY_PHASE)
+	check_dependencies ()
+	if (NOT FOUND_DEPENDENCIES)
+		remove_plugin (yambi ${FAILURE_MESSAGE})
+	endif (NOT FOUND_DEPENDENCIES)
+
+	set (SOURCE_FILES_INPUT input.hpp input.cpp)
+
+	if (ENABLE_ASAN AND CMAKE_COMPILER_IS_GNUCXX)
+		# ~~~
+		# Ignore runtime error about member call on address, which does not point to object of type `__codecvt_abstract_base`.
+		# See also: https://gcc.gnu.org/bugzilla/show_bug.cgi?id=81068
+		# ~~~
+		set_source_files_properties (${SOURCE_FILES_INPUT} PROPERTIES COMPILE_FLAGS "-fno-sanitize=undefined")
+	endif (ENABLE_ASAN AND CMAKE_COMPILER_IS_GNUCXX)
+
+	set (SOURCE_FILES
+	     convert.hpp
+	     convert.cpp
+	     driver.hpp
+	     driver.cpp
+	     lexer.hpp
+	     lexer.cpp
+	     yambi.hpp
+	     yambi.cpp
+	     ${SOURCE_FILES_INPUT}
+	     ${BISON_YAMBI_OUTPUT_SOURCE}
+	     ${BISON_YAMBI_OUTPUT_HEADER})
+endif (DEPENDENCY_PHASE)
+
+add_plugin (yambi
+	    CPP
+	    ADD_TEST
+	    CPP_TEST
+	    INSTALL_TEST_DATA
+	    TEST_README
+	    TEST_REQUIRED_PLUGINS directoryvalue
+				  yamlsmith
+	    SOURCES ${SOURCE_FILES}
+	    INCLUDE_DIRECTORIES ${CMAKE_CURRENT_SOURCE_DIR})

src/plugins/yambi/README.md

@@ -0,0 +1,87 @@
+- infos = Information about the yambi plugin is in keys below
+- infos/author = René Schwaiger <sanssecours@me.com>
+- infos/licence = BSD
+- infos/needs = directoryvalue yamlsmith
+- infos/provides = storage/yaml
+- infos/recommends =
+- infos/placements = getstorage
+- infos/status = maintained unittest preview experimental unfinished nodoc concept discouraged
+- infos/metadata =
+- infos/description = This storage plugin use a parser generated by Bison to read YAML files
+
+# YAMBi
+
+## Introduction
+
+This plugin uses Bison to generate a parser for the [YAML](http://yaml.org) serialization format.
+
+## Dependencies
+
+The plugin requires [Bison](https://www.gnu.org/software/bison/) (3.0 or later).
+
+## Examples
+
+### Mappings
+
+```sh
+# Mount plugin
+sudo kdb mount config.yaml user/tests/yambi yambi
+
+kdb set user/tests/yambi/bambi 'Mule Deer'
+kdb get user/tests/yambi/bambi
+#> Mule Deer
+
+kdb set user/tests/yambi/thumper 'Rabbit'
+kdb get user/tests/yambi/thumper
+#> Rabbit
+
+kdb set user/tests/yambi/bambi/baby 'Bobby Stewart'
+kdb set user/tests/yambi/bambi/young 'Donnie Dunagan'
+kdb set user/tests/yambi/bambi/adolescent 'Hardie Albright'
+kdb set user/tests/yambi/bambi/adult 'John Sutherland'
+
+kdb get user/tests/yambi/bambi/baby
+#> Bobby Stewart
+
+kdb ls user/tests/yambi
+#> user/tests/yambi/bambi
+#> user/tests/yambi/bambi/adolescent
+#> user/tests/yambi/bambi/adult
+#> user/tests/yambi/bambi/baby
+#> user/tests/yambi/bambi/young
+#> user/tests/yambi/thumper
+
+# Undo modifications
+kdb rm -r user/tests/yambi
+sudo kdb umount user/tests/yambi
+```
+
+### Arrays
+
+```sh
+# Mount plugin
+sudo kdb mount config.yaml user/tests/yambi yambi
+
+kdb set user/tests/yambi/friends
+kdb set user/tests/yambi/friends/#0 Thumper
+kdb set user/tests/yambi/friends/#1 Flower
+
+# Retrieve last array index
+kdb getmeta user/tests/yambi/friends array
+#> #1
+
+kdb get user/tests/yambi/friends/#0
+#> Thumper
+kdb get user/tests/yambi/friends/#1
+#> Flower
+
+# Undo modifications
+kdb rm -r user/tests/yambi
+sudo kdb umount user/tests/yambi
+```
+
+## Limitations
+
+The plugin supports the same limited YAML syntax as [Yan LR](../yanlr/).
+
+- The plugin always assumes **UTF-8** encoded data.

src/plugins/yambi/convert.cpp

@@ -0,0 +1,69 @@
+/**
+ * @file
+ *
+ * @brief This file contains a function to convert a YAML file to a key set.
+ *
+ * @copyright BSD License (see LICENSE.md or https://www.libelektra.org)
+ */
+
+// -- Imports ------------------------------------------------------------------
+
+#include "kdberrors.h"
+
+#include "convert.hpp"
+#include "driver.hpp"
+
+using std::string;
+
+using CppKey = kdb::Key;
+using CppKeySet = kdb::KeySet;
+
+// -- Function -----------------------------------------------------------------
+
+/**
+ * @brief This function converts the given YAML file to keys and adds the
+ *        result to `keySet`.
+ *
+ * @param keySet The function adds the converted keys to this variable.
+ * @param parent The function uses this parent key of `keySet` to emit error
+ *               information.
+ * @param filename This parameter stores the path of the YAML file this
+ *                 function converts.
+ *
+ * @retval -3 if the file could not be opened for reading
+ * @retval -2 if parsing was unsuccessful due to memory exhaustion
+ * @retval -1 if there was an syntax error converting the YAML file
+ * @retval  0 if parsing was successful and the function did not change the given keyset
+ * @retval  1 if parsing was successful and the function did change `keySet`
+ */
+int addToKeySet (CppKeySet & keySet, CppKey & parent, string const & filename)
+{
+	Driver driver{ parent };
+
+	int status = driver.parse (filename);
+
+	if (status < 0)
+	{
+		if (status == -3)
+		{
+			ELEKTRA_SET_ERRORF (ELEKTRA_ERROR_COULD_NOT_OPEN, parent.getKey (), "Unable to open file “%s”", filename.c_str ());
+		}
+		else if (status == -2)
+		{
+			ELEKTRA_SET_ERROR (ELEKTRA_ERROR_PARSE, parent.getKey (), "Parsing failed due to memory exhaustion");
+		}
+		else if (status == -1)
+		{
+			ELEKTRA_SET_ERROR (ELEKTRA_ERROR_PARSE, parent.getKey (), driver.getErrorMessage ().c_str ());
+		}
+
+		return status;
+	}
+
+	CppKeySet keys = driver.getKeySet ();
+	status = (keys.size () <= 0) ? 0 : 1;
+
+	keySet.append (keys);
+
+	return status;
+}

src/plugins/yambi/convert.hpp

@@ -0,0 +1,36 @@
+/**
+ * @file
+ *
+ * @brief This file contains a function to convert a YAML file to a key set.
+ *
+ * @copyright BSD License (see LICENSE.md or https://www.libelektra.org)
+ */
+
+#ifndef ELEKTRA_PLUGIN_YAMBI_CONVERTER_HPP
+#define ELEKTRA_PLUGIN_YAMBI_CONVERTER_HPP
+
+// -- Imports ------------------------------------------------------------------
+
+#include <kdb.hpp>
+
+// -- Function -----------------------------------------------------------------
+
+/**
+ * @brief This function converts the given YAML file to keys and adds the
+ *        result to `keySet`.
+ *
+ * @param keySet The function adds the converted keys to this variable.
+ * @param parent The function uses this parent key of `keySet` to emit error
+ *               information.
+ * @param filename This parameter stores the path of the YAML file this
+ *                 function converts.
+ *
+ * @retval -3 if the file could not be opened for reading
+ * @retval -2 if parsing was unsuccessful due to memory exhaustion
+ * @retval -1 if there was an syntax error converting the YAML file
+ * @retval  0 if parsing was successful and the function did not change the given keyset
+ * @retval  1 if parsing was successful and the function did change `keySet`
+ */
+int addToKeySet (kdb::KeySet & keySet, kdb::Key & parent, std::string const & filename);
+
+#endif // ELEKTRA_PLUGIN_YAMBI_CONVERTER_HPP