Opts plugin

cmake/Modules/LibAddLib.cmake

@@ -12,7 +12,7 @@ function (add_lib name)
 
 	if (BUILD_SHARED)
 		add_library (elektra-${name} SHARED ${ARG_SOURCES})
-		add_dependencies (elektra-${name} kdberrors_generated elektra_error_codes_generated)
+		add_dependencies (elektra-${name} kdberrors_generated elektra_error_codes_generated ${ARG_LINK_ELEKTRA})
 
 		target_link_libraries (elektra-${name} elektra-core ${ARG_LINK_ELEKTRA})
 	endif (BUILD_SHARED)

doc/news/_preparation_next_release.md

@@ -51,7 +51,25 @@ the `type` plugin will ignore the key. We now also support converting enum value
 To switch from `boolean` to the new `type`, you don't have to do anything, if you used the default config. If you used a custom configuration
 please take a look at the [README](https://www.libelektra.org/plugins/type).
 
-### <<HIGHLIGHT2>>
+### kdbEnsure
+
+`kdbEnsure` is a new function in `elektra-kdb`. It can be used to ensure that a KDB instance meets certain conditions specified in a
+contract. In principle this a very powerful tool that may be used for a lot of things. For now it only supports a few conditions concerning
+plugins:
+
+- You can specify that a plugin should be mounted globally. This is can for example be used to enable the new [gopts](#gopts) plugin.
+- Conversely you can also define that a plugin should not be mounted globally, e.g. to disable the `spec` plugin, which is enabled by default.
+- Additionally you may want to enforce that a global plugin uses a certain configuration. For this case you can specify that the plugin
+  should be remounted, i.e. unmounted and immediately mounted again.
+- In future non-global plugins will support the same features. But because of the different architecture involved, for now only unmounting
+  non-global plugins is supported.
+
+All changes made by `kdbEnsure` are purely temporary. They will only apply to the KDB handle passed to the function.
+
+IMPORTANT: `kdbEnsure` only works, if the `list` plugin is mounted in all appropriate global positions.
+
+Note: `kdbEnsure` right now ignores the `infos/recommends` and `infos/needs` metadata of plugins, so you have to explicitly take care of
+dependencies. _(Klemens Böswirth)_
 
 ### <<HIGHLIGHT2>>
 
@@ -155,6 +173,15 @@ The following section lists news about the [modules](https://www.libelektra.org/
 
 - We fixed an incorrect format specifier in a call to the `syslog` function. _(René Schwaiger)_
 
+### gOpts
+
+- The [gopts](https://www.libelektra.org/plugins/gopts) plugin simply retrieves the values of `argc`, `argv` and `envp` needed for
+  [`elektraGetOpts`](https://www.libelektra.org/tutorials/command-line-options) and then makes the call. It is intended to be used as a
+  global plugin, so that command-line options are automatically parsed when `kdbGet` is called. _(Klemens Böswirth)_
+- The plugin works under WIN32 (via `GetCommandLineW` and `GetEnvironmentString`), MAC_OSX (`_NSGetArgc`, `_NSGetArgv`) and any system that
+  either has a `sysctl(3)` function that accepts `KERN_PROC_ARGS` (e.g. FreeBSD) or when `procfs` is mounted and either `/proc/self` or
+  `/proc/curproc` refers to the current process. If you need support for any other systems, feel free to add an implementation.
+
 ## Libraries
 
 The text below summarizes updates to the [C (and C++)-based libraries](https://www.libelektra.org/libraries/readme) of Elektra.
@@ -171,7 +198,7 @@ compiled against an older 0.8 version of Elektra will continue to work
 
 ### Core
 
-- <<TODO>>
+- `kdbGet` now calls global postgetstorage plugins with the parent key passed to `kdbGet`, instead of a random mountpoint. _(Klemens Böswirth)_
 - <<TODO>>
 - <<TODO>>
 

doc/tutorials/validation.md

@@ -318,6 +318,7 @@ Before we look further let us undo the modifications to the key database.
 ```sh
 kdb rm -r spec/tests/tutorial
 kdb rm -r system/tests/tutorial
+kdb rm -rf user/tests/tutorial
 kdb umount spec/tests/tutorial
 kdb umount /tests/tutorial
 kdb rm -rf spec

src/bindings/cpp/examples/cpp_example_userexception.cpp

@@ -121,9 +121,29 @@ class KDBException : public Exception
 		return "User Exception: KDB";
 	}
 
-private:
+protected:
 	Key m_key;
 };
+
+class ContractException : public KDBException
+{
+public:
+	explicit ContractException (Key key) : KDBException (key)
+	{
+	}
+
+	~ContractException () noexcept override = default;
+
+	const char * what () const noexcept override
+	{
+		if (!m_key)
+		{
+			return "Malformed contract";
+		}
+		return KDBException::what ();
+	}
+};
+
 } // namespace kdb
 
 

src/bindings/cpp/include/kdb.hpp

@@ -56,6 +56,8 @@ class KDB
 	virtual inline int set (KeySet & returned, std::string const & keyname);
 	virtual inline int set (KeySet & returned, Key & parentKey);
 
+	inline int ensure (const KeySet & contract, Key & parentKey);
+
 private:
 	ckdb::KDB * handle; ///< holds an kdb handle
 };
@@ -232,6 +234,33 @@ inline int KDB::set (KeySet & returned, Key & parentKey)
 	return ret;
 }
 
+/**
+ * Ensures that the conditions defined in @p contract are met by this KDB.
+ *
+ * @see ckdb::kdbEnsure()
+ *
+ * @param contract  The contract to ensure.
+ * @param parentKey The parentKey to use.
+ *
+ * @throw KDBException if there were problems with the contract or the database
+ * @throw ContractException if the contract couldn't be ensured
+ */
+int KDB::ensure (const KeySet & contract, Key & parentKey)
+{
+	// have to ksDup because contract is consumed and ksDel()ed by kdbEnsure
+	int ret = ckdb::kdbEnsure (handle, ckdb::ksDup (contract.getKeySet ()), parentKey.getKey ());
+	if (ret == -1)
+	{
+		throw KDBException (parentKey);
+	}
+	if (ret == 1)
+	{
+		throw ContractException (parentKey);
+	}
+	return ret;
+}
+
+
 } // end of namespace kdb
 
 #endif

src/bindings/cpp/include/kdbexcept.hpp

@@ -60,10 +60,30 @@ class KDBException : public Exception
 		return m_str.c_str ();
 	}
 
-private:
+protected:
 	Key m_key;
 	mutable std::string m_str;
 };
+
+class ContractException : public KDBException
+{
+public:
+	explicit ContractException (Key key) : KDBException (key)
+	{
+	}
+
+	~ContractException () noexcept override = default;
+
+	const char * what () const noexcept override
+	{
+		if (!m_key)
+		{
+			return "Malformed contract";
+		}
+		return KDBException::what ();
+	}
+};
+
 } // namespace kdb
 
 #endif

src/error/specification

@@ -1339,3 +1339,9 @@ severity:error
 ingroup:plugin
 module:specload
 macro:SPECLOAD
+
+number:213
+description:the contract was malformed
+severity:error
+ingroup:kdb
+macro:MALFORMED_CONTRACT

src/include/kdb.h.in

@@ -110,6 +110,7 @@ int kdbGet(KDB *handle, KeySet *returned,
 int kdbSet(KDB *handle, KeySet *returned,
 	Key *parentKey);
 
+int kdbEnsure (KDB * handle, KeySet * contract, Key * parentKey);
 
 
 /**************************************

src/include/kdbconfig.h.in

@@ -202,7 +202,4 @@
 
 
 
-
-
-
 #endif

src/include/kdbglobal.h

@@ -30,6 +30,7 @@
 	POSITION(GETRESOLVER) \
 	POSITION(PREGETSTORAGE) \
 	POSITION(GETSTORAGE) \
+	POSITION(PROCGETSTORAGE) \
 	POSITION(POSTGETSTORAGE) \
 	POSITION(SETRESOLVER) \
 	POSITION(POSTGETCLEANUP) \

src/include/kdbprivate.h

@@ -323,9 +323,6 @@ struct _KDB
 
 	ElektraIoInterface * ioBinding; /*!< binding for asynchronous I/O operations.*/
 
-	Plugin * notificationPlugin; /*!< reference to global plugin for notifications.*/
-	ElektraNotificationCallbackContext * notificationCallbackContext; /*!< reference to context for notification callbacks.*/
-
 	KeySet * global; /*!< This keyset can be used by plugins to pass data through
 			the KDB and communicate with other plugins. Plugins shall clean
 			up their parts of the global keyset, which they do not need any more.*/
@@ -519,6 +516,7 @@ int elektraProcessPlugin (Key * cur, int * pluginNumber, char ** pluginName, cha
 int elektraProcessPlugins (Plugin ** plugins, KeySet * modules, KeySet * referencePlugins, KeySet * config, KeySet * systemConfig,
 			   KeySet * global, Key * errorKey);
 size_t elektraPluginGetFunction (Plugin * plugin, const char * name);
+Plugin * elektraPluginFindGlobal (KDB * handle, const char * pluginName);
 
 Plugin * elektraPluginMissing (void);
 Plugin * elektraPluginVersion (void);

src/include/kdbproposal.h

@@ -89,7 +89,6 @@ int keyRel2 (const Key * k1, const Key * k2, KeyRelType which);
 Key * keyAsCascading (const Key * key);
 int keyGetLevelsBelow (const Key * k1, const Key * k2);
 
-
 #ifdef __cplusplus
 }
 }