highlevel: remove most of error handling from public API

doc/news/_preparation_next_release.md

@@ -66,7 +66,7 @@ types and functions have to be mapped to provide the full functionality.
 
 Take a look at the [README](/src/libs/highlevel/README.md) for more infos.
 
-For examples on how to build an application using this API take a look at our [example](/examples/highlevel). _(Klemens Böswirth)_
+For an example on how to build an application using this API take a look at [this](/examples/highlevel). _(Klemens Böswirth)_
 
 ### <<HIGHLIGHT2>>
 

src/error/exporterrors.cpp

@@ -524,6 +524,7 @@ static ostream & printPrivate (ostream & os, parse_t & p)
 	   << endl
 	   << "#include <elektra/types.h>" << endl
 	   << "#include <elektra/error.h>" << endl
+	   << "#include <kdbprivate.h>" << endl
 	   << endl
 	   << "#ifdef __cplusplus" << endl
 	   << "extern \"C\" {" << endl

src/include/elektra/error.h

@@ -20,34 +20,10 @@ extern "C" {
 
 typedef struct _ElektraError ElektraError;
 
-typedef enum
-{
-	/**
-	 * Use only, if the error will be raised with elektraFatalError().
-	 */
-	ELEKTRA_ERROR_SEVERITY_FATAL = 0,
-	ELEKTRA_ERROR_SEVERITY_ERROR,
-	ELEKTRA_ERROR_SEVERITY_WARNING
-} ElektraErrorSeverity;
-
-typedef const char * ElektraKDBErrorGroup;
-typedef const char * ElektraKDBErrorModule;
-
 typedef void (*ElektraErrorHandler) (ElektraError * error);
 
 ElektraErrorCode elektraErrorCode (const ElektraError * error);
 const char * elektraErrorDescription (const ElektraError * error);
-ElektraErrorSeverity elektraErrorSeverity (const ElektraError * error);
-
-int elektraKDBErrorCode (const ElektraError * error);
-const char * elektraKDBErrorDescription (const ElektraError * error);
-ElektraErrorSeverity elektraKDBErrorSeverity (const ElektraError * error);
-ElektraKDBErrorGroup elektraKDBErrorGroup (const ElektraError * error);
-ElektraKDBErrorModule elektraKDBErrorModule (const ElektraError * error);
-const char * elektraKDBErrorReason (const ElektraError * error);
-int elektraKDBErrorWarningCount (const ElektraError * error);
-ElektraError * elektraKDBErrorGetWarning (const ElektraError * error, int index);
-Key * elektraKDBErrorKey (const ElektraError * error);
 
 void elektraErrorReset (ElektraError ** error);
 

src/include/kdbprivate.h

@@ -616,6 +616,19 @@ int elektraGlobalError (KDB * handle, KeySet * ks, Key * parentKey, int position
 extern "C" {
 #endif
 
+typedef enum
+{
+	/**
+	 * Use only, if the error will be raised with elektraFatalError().
+	 */
+	ELEKTRA_ERROR_SEVERITY_FATAL = 0,
+	ELEKTRA_ERROR_SEVERITY_ERROR,
+	ELEKTRA_ERROR_SEVERITY_WARNING
+} ElektraErrorSeverity;
+
+typedef const char * ElektraKDBErrorGroup;
+typedef const char * ElektraKDBErrorModule;
+
 struct _Elektra
 {
 	KDB * kdb;
@@ -652,6 +665,19 @@ void elektraSetLookupKey (Elektra * elektra, const char * name);
 void elektraSetArrayLookupKey (Elektra * elektra, const char * name, kdb_long_long_t index);
 ElektraError * elektraErrorCreate (ElektraErrorCode code, const char * description, ElektraErrorSeverity severity);
 
+// error handling unstable/private for now
+ElektraErrorSeverity elektraErrorSeverity (const ElektraError * error);
+
+int elektraKDBErrorCode (const ElektraError * error);
+const char * elektraKDBErrorDescription (const ElektraError * error);
+ElektraErrorSeverity elektraKDBErrorSeverity (const ElektraError * error);
+ElektraKDBErrorGroup elektraKDBErrorGroup (const ElektraError * error);
+ElektraKDBErrorModule elektraKDBErrorModule (const ElektraError * error);
+const char * elektraKDBErrorReason (const ElektraError * error);
+int elektraKDBErrorWarningCount (const ElektraError * error);
+ElektraError * elektraKDBErrorGetWarning (const ElektraError * error, int index);
+Key * elektraKDBErrorKey (const ElektraError * error);
+
 #ifdef __cplusplus
 }
 #undef Key

src/libs/highlevel/README.md

@@ -128,8 +128,9 @@ initializing a new variable with `ElektraError * error = NULL` or by reusing an
 Notice, that you should always check if an error occurred by comparing it to `NULL` after the function call.
 
 If an error happened, it is often useful to show an error message to the user. A description of what went wrong is provided in the
-`ElektraError` struct and can be accessed using `elektraErrorDescription (error)`. A complete list of the provided accessors for
-error-details can be found in [elektra_error.c](/src/libs/highlevel/elektra_error.c).
+`ElektraError` struct and can be accessed using `elektraErrorDescription (error)`. Additionally the error code can be accessed through
+`elektraErrorCode (error)`.
+NOTE: The error API is still a work in progress, so more functions will likely be added in the future.
 
 To avoid leakage of memory, you have to call `elektraErrorReset (&error)` (ideally as soon as you are finished resolving the error):
 
@@ -149,40 +150,6 @@ if (error != NULL)
 }
 ```
 
-#### Low-level Errors
-
-Errors which do not originate inside the high-level API itself are wrapped into a `ElektraError` struct with error code
-`ELEKTRA_ERROR_CODE_LOW_LEVEL`. The high-level Error API provides methods (`elektraKDBError*`) to access the properties of the low-level
-error. You can also access the key to which the error was originally attached, as well as any possible low-level warnings.
-
-To get the original low-level error code, description, severity, group, module and reason you can use these functions:
-
-```c
-int elektraKDBErrorCode (const ElektraError * error);
-const char * elektraKDBErrorDescription (const ElektraError * error);
-ElektraErrorSeverity elektraKDBErrorSeverity (const ElektraError * error);
-ElektraKDBErrorGroup elektraKDBErrorGroup (const ElektraError * error);
-ElektraKDBErrorModule elektraKDBErrorModule (const ElektraError * error);
-const char * elektraKDBErrorReason (const ElektraError * error);
-```
-
-To iterate over all the warnings use the following to functions:
-
-```c
-int elektraKDBErrorWarningCount (const ElektraError * error);
-ElektraError * elektraKDBErrorGetWarning (const ElektraError * error, int index);
-```
-
-`elektraKDBErrorGetWarning` will return a newly allocated `ElektraError` struct with error code `ELEKTRA_ERROR_CODE_LOW_LEVEL` and severity
-`ELEKTRA_ERROR_SEVERITY_WARNING`. You will need to free the allocated struct when you are done. To access the information of the low-level
-warning you use the `elektraKDBError*` functions described above.
-
-The key to which the low-level error and the associated warnings where attached originally can be accessed via:
-
-```c
-Key * elektraKDBErrorKey (const ElektraError * error);
-```
-
 ### Configuration
 
 Currently there is only one way to configure an `Elektra` instance:

tests/kdb/testkdb_highlevel.cpp

@@ -12,6 +12,7 @@
 
 #include <gtest/gtest-elektra.h>
 #include <kdbhelper.h>
+#include <kdbprivate.h>
 
 #define EXPECT_KEYVALUE(Key, Value) EXPECT_PRED2 (keyHasValue, Key, Value)
 #define EXPECT_KEYMETA(Key, Meta, Value) EXPECT_PRED3 (keyHasMetaValue, Key, Meta, Value)