Kdb rewrite base

.github/ISSUE_TEMPLATE.md

@@ -17,7 +17,7 @@ kdb get user:/tests/hello
 
 kdb get user:/tests/hello/does/not/exist
 # RET: 11
-# STDERR: [Dd]id not find key 'user:/tests/hello/does/not/exist'
+# STDERR: .*[Dd]id not find key 'user:/tests/hello/does/not/exist'
 
 kdb rm user:/tests/hello
 ```

doc/dev/README.md

@@ -25,5 +25,6 @@ It complements the man pages found [here](/doc/help).
 ## Internals
 
 - [Algorithm](algorithm.md)
+- [Add C command to KDB](kdb-add-new-command.md)
 - [Plugins Ordering](plugins-ordering.md)
 - [KDB Operations](kdb-operations.md)

doc/dev/error-categorization.md

@@ -161,6 +161,16 @@ the values (`enum` plugin), etc.
 Users should try a different value or fix the underlying specification and retry
 again.
 
+#### CLI ("C03300", concrete)
+
+Command Line Interface (CLI) Errors are errors that occur due to problematic interactions with the application via the command line.
+These types of errors typically involve an issue with the user's input or a misunderstanding of the application's expected command structure and specifications.
+
+The primary focus of this category is on correctly executing command line instructions and ensuring communication between the user and the application is as intended.
+CLI errors can occur when users attempt to execute commands that do not align with the application's requirements, despite the command's syntactical correctness.
+
+By correctly categorizing and handling CLI errors, developers can improve the application's usability and robustness, ensuring accurate responses to user commands and better overall command line experience.
+
 ## Underlying design decision document
 
 - [Decision Document](../decisions/6_implemented/error_codes.md) The underlying design

doc/dev/kdb-add-new-command.md

@@ -0,0 +1,171 @@
+# Implement new commands in C
+
+Here we'll go over the basic requirements to implement a new command in C and integrate it in to the `kdb` CLI framework.
+
+## 1. Files
+
+First we need a header as well as a c file for the new command in `src/tools/kdb`.
+
+### Header
+
+The `<name>.h` has to look something like this:
+
+```c
+/**
+ * @file
+ *
+ * @brief Header for ... command
+ *
+ * @copyright BSD License (see LICENSE.md or https://www.libelektra.org)
+ */
+
+#ifndef ELEKTRA_KDB_..._H
+#define ELEKTRA_KDB_..._H
+
+#include <kdb.h>
+
+/**
+ * Adds options specification of complete command to @spec
+ *
+ * @param spec the base spec where the commands spec should be added
+ */
+void add...Spec (KeySet * spec);
+
+/**
+ * Executes the ... command
+ *
+ * @param options cli options and arguments as specified in addCompleteSpec()
+ * @param errorKey key where errors and warnings should be saved
+ *
+ * @retval 0 ... command ran without errors
+ * @retval 1 errors occurred, keyGetMeta (errorKey, "error/reason") for info
+ *
+ */
+int exec... (KeySet * options, Key * errorKey);
+
+#endif // ELEKTRA_KDB_..._H
+```
+
+### `C` file
+
+The `<name>.c` has to implement the two functions already described in the header file, in addition to those `COMMAND_NAME` has to be defined before `#include <command.h>`.
+This is important because macros defined in `command.h` depend on `COMMAND_NAME` being defined.
+
+```c
+#define COMMAND_NAME "..." // your command name
+...
+#include <command.h>
+...
+```
+
+In addition to `command.h`, it should also `#include <colors.h>`.
+`command.h` and `colors.h` contain all the needed helper macros and functions.
+
+#### Specification
+
+`void add...Spec (KeySet * spec)` will contain the specification (for `elektraGetOpts`) of the new command.
+It has to append it to the passed `KeySet * spec`, the framework will call this function to register its specification.
+The function could look something like this:
+
+```c
+void addGetSpec (KeySet * spec)
+{
+	ksAppendKey (spec, keyNew (COMMAND_SPEC_KEY (COMMAND_NAME), KEY_META, "description", "Get the value of an individual key.",
+				   KEY_META, "command", COMMAND_NAME, KEY_END));
+	ksAppendKey (spec, keyNew (COMMAND_SPEC_KEY (COMMAND_NAME) "/all", KEY_META, "description", "Consider all of the keys", KEY_META,
+				   "opt", "a", KEY_META, "opt/long", "all", KEY_META, "opt/arg", "none", KEY_END));
+	ksAppendKey (spec, keyNew (COMMAND_SPEC_KEY (COMMAND_NAME) "/name", KEY_META, "description", "The name of the key", KEY_META,
+				   "args", "indexed", KEY_META, "args/index", "0", KEY_END));
+
+	ADD_BASIC_OPTIONS (spec, COMMAND_SPEC_KEY (COMMAND_NAME))
+}
+```
+
+The `ADD_BASIC_OPTIONS` at the end adds options that are common across all commands to its spec, this includes things like `verbose: -v` or `debug: -d`.
+
+#### Execution
+
+The `int exec... (KeySet * options, Key * errorKey)` receives two parameters, `options` and `errorKey`.
+Where `options` contains the passed options (as parsed by `elektraGetOpts`) and arguments and `errorKey` is where any errors or warnings have to be written to so the framework can properly print them.
+It should start with the `GET_BASIC_OPTIONS` macro, this sets everything up needed for logging(and logging level), basic options and colored printing.
+So afterward `CLI_PRINT` and `CLI_ERROR_PRINT` can be used.
+When returning for the `exec` function the `RETURN (n)` macro should be used, it makes sure things allocated by `GET_BASIC_OPTIONS` are freed properly.
+A basic version of this function could look something like this:
+
+```c
+int ret = 0;
+	GET_BASIC_OPTIONS
+
+	bool all = false;
+	tmp = GET_OPTION_KEY (options, "all");
+	if (tmp != NULL)
+	{
+		elektraKeyToBoolean (GET_OPTION_KEY (options, "all"), &all);
+		keyDel (tmp);
+	}
+
+    ...
+
+	Key * toLookUp = getKeyFromOptions (GET_OPTION (options, "name"), errorKey, verbose);
+	if (toLookUp == NULL)
+	{
+		RETURN (2)
+	}
+
+    ...
+
+	if (found == NULL)
+	{
+		CLI_ERROR_PRINT (CLI_LOG_NONE, "Did not find key '%s'", RED (keyName (toLookUp)));
+		ret = 11;
+		goto cleanup;
+	}
+
+	if (keyGetNamespace (found) == KEY_NS_DEFAULT)
+	{
+		CLI_PRINT (CLI_LOG_VERBOSE, "The key was not found in any other namespace, taking the %s\n", BOLD ("default"));
+	}
+
+	...
+
+cleanup:
+	...
+
+	RETURN (ret)
+```
+
+For getting keys from arguments the helper function `getKeyFromOptions` can the used.
+It will resolve bookmarks and make sure the argument is a valid keyname.
+
+## 2. Output
+
+All output in the `exec` function should be done using either `CLI_PRINT` or `CLI_ERROR_PRINT` with the appropriate logging level.
+Available logging levels are `CLI_LOG_NONE`, `CLI_LOG_VERBOSE` and `CLI_LOG_DEBUG`.
+By using `CLI_PRINT` or `CLI_ERROR_PRINT` logging levels are handled automatically.
+
+## 3. Errors/Warning
+
+If errors occur during the execution of your command, they should be set in `errorKey` and not printed directly.
+This could look something like this:
+
+```c
+ELEKTRA_SET_INTERNAL_ERROR (errorKey, "could not copy key meta to errorKey");
+```
+
+These error setting macros are available in `kdberrors.h`.
+By setting the like this, they are later printed properly formatted by the framework.
+
+## 4. "registering" the new command
+
+You just have to `#include` your header file in [`main.c`](/src/tools/kdb/main.c) and add an element to the `command subcommands[]` array.
+
+```c
+command subcommands[] = {
+	...
+	{ "your-new-command-name", add...Spec, exec... },
+};
+```
+
+## _5. Validate_
+
+After following these steps the new command will show up when typing `kdb --help` and `kdb <your-cmd-name> --help` will show a usage message based on the specification you have provided in the `add...Spec` function.

doc/help/kdb-cache.md

@@ -19,11 +19,9 @@ subcommand can only remove a user's cache files (i.e. not system wide).
 ## OPTIONS
 
 - `-H`, `--help`:
-  Show the man page.
+  Show usage of command.
 - `-V`, `--version`:
   Print version info.
-- `-p`, `--profile <profile>`:
-  Use a different kdb profile.
 - `-C`, `--color <when>`:
   Print never/auto(default)/always colored output.
 - `-v`, `--verbose`:

doc/help/kdb-complete.md

@@ -2,11 +2,10 @@
 
 ## SYNOPSIS
 
-`kdb complete [path]`
+`kdb complete path`
 
 Where `path` is the path for which the user would like to receive completion suggestion.
-If `path` is not specified, it will show every possible completion. It's synonymous
-to calling `kdb complete ""`.
+Calling `kdb complete ""` will show every possible completion.
 
 ## DESCRIPTION
 
@@ -22,11 +21,9 @@ originates from.
 ## OPTIONS
 
 - `-H`, `--help`:
-  Show the man page.
+  Show usage of command.
 - `-V`, `--version`:
   Print version info.
-- `-p`, `--profile <profile>`:
-  Use a different kdb profile.
 - `-C`, `--color <when>`:
   Print never/auto(default)/always colored output.
 - `-m`, `--min-depth <min-depth>`:
@@ -69,7 +66,7 @@ kdb complete user:/ --max-depth=1
 # STDOUT-REGEX: .+
 
 # list all possible namespaces or mount points, only the current level
-kdb complete --max-depth=1
+kdb complete "" --max-depth=1
 # STDOUT-REGEX: .+
 
 # list suggestions for /tests/complete/examples/kdb-complete, only the current level

doc/help/kdb-convert.md

@@ -23,11 +23,9 @@ If either `import-file` or `export-file` are not specified, `stdin` and `stdout`
 ## OPTIONS
 
 - `-H`, `--help`:
-  Show the man page.
+  Show usage of command.
 - `-V`, `--version`:
   Print version info.
-- `-p`, `--profile <profile>`:
-  Use a different kdb profile.
 - `-C`, `--color <when>`:
   Print never/auto(default)/always colored output.
 - `-v`, `--verbose`:

doc/help/kdb-cp.md

@@ -33,11 +33,9 @@ This command will return the following values as an exit status:
 ## OPTIONS
 
 - `-H`, `--help`:
-  Show the man page.
+  Show usage of command.
 - `-V`, `--version`:
   Print version info.
-- `-p`, `--profile <profile>`:
-  Use a different kdb profile.
 - `-C`, `--color <when>`:
   Print never/auto(default)/always colored output.
 - `-r`, `--recursive`:

doc/help/kdb-editor.md

@@ -35,11 +35,9 @@ The user should specify the format that the current configuration or keys are in
 ## OPTIONS
 
 - `-H`, `--help`:
-  Show the man page.
+  Show usage of command.
 - `-V`, `--version`:
   Print version info.
-- `-p`, `--profile <profile>`:
-  Use a different kdb profile.
 - `-C`, `--color <when>`:
   Print never/auto(default)/always colored output.
 - `-s`, `--strategy <name>`: