decisions: new categories

doc/DESIGN.md

@@ -56,30 +56,22 @@ are more allocations happening, but they are invisible to the user of
 the API and happen implicitly within any of these 3 classes:
 `KDB`, `Key` and `KeySet`.
 
-Key names and values cannot be handled as easy, because Elektra
-does not provide a string library. There are 2 ways to access the
-mentioned attributes. The function
+Key names and values cannot be handled as easy without helper libraries,
+because Elektra does not provide a string library. The function
 
 ```c
-const char *keyString(const Key *key);
+const void *keyValue(const Key *key);
 ```
 
-returns a string. You are not allowed to change the returned string.
+returns a value. You are not allowed to change the returned value.
+The life time is bound to the `Key`.
 The function
 
 ```c
-ssize_t keyGetValueSize(const Key *key);
-```
-
-shows how long the string is for the specified key. The returned value
-also specifies the minimum buffer size that `keyGetString` will
-reserve for the copy of the key.
-
-```c
-ssize_t keyGetString(const Key *key, char *returnedValue, size_t maxSize);
+ssize_t keyValueSize(const Key *key);
 ```
 
-writes the comment in a buffer maintained by you.
+gives the length of the value in bytes.
 
 ## Variable Arguments
 
@@ -124,68 +116,6 @@ database. The functions are implemented in `src/libs/elektra` in ANSI C.
 
 Useful extensions are available in [further libraries](/src/libs).
 
-## Value, String or Binary
-
-Sometimes people confuse the terms “value”, “string” and “binary”:
-
-- Value is just a name which does not specify if data is stored as
-  string or in binary form.
-
-- A string is a char array, with a terminating `'\0'`.
-
-- Binary data is stored in an array of type void, and not terminated by
-  `'\0'`.
-
-See also [the glossary](/doc/help/elektra-glossary.md) for further
-terminology.
-
-In Elektra `char*` are used as null-terminated strings, while `void*`
-might contain `0`-bytes:
-
-```c
-const void *keyValue(const Key *key);
-```
-
-does not specify whether the returned value is binary or a string. The
-function just returns the pointer to the value. When `key` is a string
-(check with `keyIsString`) at least `""` will be returned. See section
-“Return Values” to learn more about common values returned by Elektra’s
-functions. For binary data a `NULL` pointer is also possible to
-distinguish between no data and `'\0'`.
-
-```c
-ssize_t keyGetValueSize(const Key *key);
-```
-
-does not specify whether the key type is binary or string. The function
-just returns the size which can be passed to `elektraMalloc` to hold
-the entire value.
-
-```c
-ssize_t keyGetString(const Key *key, char *returnedString, size_t maxSize);
-```
-
-stores the string into a buffer maintained by you.
-
-```c
-ssize_t keySetString(Key *key, const char *newString);
-```
-
-sets the null terminated string value for a certain key.
-
-```c
-ssize_t keyGetBinary(const Key *key, void *returnedBinary, size_t maxSize);
-```
-
-retrieves binary data which might contain `'\0'`.
-
-```c
-ssize_t keySetBinary(Key *key, const void *newBinary, size_t dataSize);
-```
-
-sets the binary data which might contain `'\0'`. The length is given
-by `dataSize`.
-
 ## Return Values
 
 Elektra’s function share common error codes. Every function must return

doc/INSTALL.md

@@ -205,11 +205,19 @@ You can find the generated packages in the `package` directory of the build dire
 
 #### Debian/Ubuntu
 
-On Debian based distributions you will need to set LD_LIBRARY_PATH before generating the package.
+First make sure you have debhelper and d-shlibs installed:
+
+```sh
+apt-get install debhelper d-shlibs
+```
+
+(Otherwise you'll see an error file utility is not available, breaking CPACK_DEBIAN_PACKAGE_SHLIBDEPS and CPACK_DEBIAN_PACKAGE_GENERATE_SHLIBS.)
+
+On Debian-based distributions you will need to set LD_LIBRARY_PATH before generating the package.
 Simply `cd` into the build directory and run following command:
 
 ```sh
-LD_LIBRARY_PATH=$(pwd)/lib:${LD_LIBRARY_PATH} make package
+LD_LIBRARY_PATH=$(pwd)/lib:${LD_LIBRARY_PATH} make package -j2
 ```
 
 To install the packages run this in the `package` directory:

doc/METADATA.ini

@@ -95,20 +95,6 @@ note = "This will rarely used within specifications, but is directly
 
 	I.e. only storage plugins set and get this property."
 
-[comment]
-type = string
-status = deprecated
-usedby/plugin = keytometa
-description = "The user's comment about the key (mostly its value).
-
-	The first line is the comment after a key-value (in the same line)
-	further lines are the lines before a key-value.
-
-	This metadata is deprecated because it assumes line-based comments
-	and cannot preserve formatting within comments."
-note = "If used within specifications it refers to the specification, not
-	the key. Use `description` to refer to the key."
-
 [comment/#]
 status = implemented
 usedby/plugin = hosts
@@ -264,15 +250,6 @@ description="Defines the type of the value, as specified in CORBA
 	The range plugin uses type as fallback, if check/type is not specified."
 example= any
 
-[binary]
-type= empty
-status= implemented
-usedby/api= keyNew keyVNew keyIsBinary keyIsString keyValue keyGetValueSize keyString keyGetString keySetString keyGetBinary keySetBinary
-usedby/plugin= binary
-description="For this metadata only the presence is significant, not its value.
-	It is used to tag binary keys. Binary keys are keys that either have no value (null keys, keyValue returns null) or a value that is
-	binary, i.e., potentially containing null bytes."
-
 
 [array]
 type = array-index

doc/decisions/README.md

@@ -16,7 +16,6 @@ section here.
 
 - [Unit Testing](unit_testing.md)
 - [Script Testing](script_testing.md)
-- [Library Split](library_split.md)
 - [Bootstrap](bootstrap.md)
 - [Empty Files](empty_files.md)
 - [CMake Plugins](cmake_plugins.md)
@@ -30,44 +29,59 @@ section here.
 - [High-level API Help Message](highlevel_help_message.md)
 - [Global KeySet](global_keyset.md)
 - [Rest API Documentation](rest_api_documentation.md)
-- [Ingroup Removal](ingroup_removal.md)
 - [Commit Function](commit_function.md)
-- [Error Message Format](error_message_format.md)
-- [Default Values](default_values.md)
-- [High Level API](high_level_api.md)
 - [Error codes](error_codes.md)
+- [Error Message Format](error_message_format.md)
 - [Error code implementation](error_code_implementation.md)
+- [Default Values](default_values.md)
 - [Semantics for Name](semantics_name.md)
 - [Base Name](base_name.md)
 - [Lookup every key](lookup_every_key.md)
 - [Holes and Non-leaf values](holes.md)
 - [Multiple File Backends](multiple_file_backends.md)
+- [Ensure](ensure.md) (@kodebach)
+- [Null](null.md)
+- [Memory Layout](memory_layout.md)
+
+## Mostly Implemented
+
+- [Array for Warnings](warning_array.md)
+- [Array](array.md)
 - [Boolean](boolean.md)
+- [Reference Counting](reference_counting.md)
 
-## In Progress
+## Decided
 
-- [Global Plugins](global_plugins.md) (@mpranj)
-- [Ensure](ensure.md) (@kodebach)
 - [Capabilities](capabilities.md) (@markus2330)
-- [Error Semantics](error_semantics.md) (API)
-- [Error Handling](error_handling.md)
-- [Remove elektraMalloc et al.](remove_elektra_malloc.md)
-- [Functions copying into buffer](functions_with_buffers.md)
+- [Make elektraMalloc et al. private](elektra_malloc.md)
 
-## Decided
+## In Progress
 
-- [Array for Warnings](warning_array.md)
-- [Array](array.md)
 - [Iterators](iterators.md)
-- [keyString() return value](key_string_return_value.md)
-- [Reference Counting](reference_counting.md)
+- Replace all internal iterators
+- Binary
+- keyName rename
+- [Simplify API](simplify_api.md) (@lawli3t will make proposal of new API)
 
 ## In Discussion
 
-- [Escaped Name](escaped_name.md) merge with:
+- [Binary](binary.md)
 - [Store the escaped and/or unescaped key name](store_name.md)
+- [keyString() return value](key_string_return_value.md)
+- [Global Plugins](global_plugins.md) (@mpranj)
+- [Error Semantics](error_semantics.md) (API)
+- [Error Handling](error_handling.md)
+- [Remove functions copying into buffer](functions_with_buffers.md)
+- [Escaped Name](escaped_name.md) merge with:
 - [Spec Expressiveness](spec_expressiveness.md)
 - [Metadata in Spec Namespace](spec_metadata.md)
+- [Elektra Prefix](elektra_prefix.md)
+- [Library Split](library_split.md)
+
+## Drafts
+
+- [Library Directory Structure](library_directory_structure.md)
+- [Header File Structure](header_file_structure.md)
 
 ## Delayed
 
@@ -76,6 +90,7 @@ section here.
 
 ## Rejected
 
+- [Key Name as separate class](separate_key_name.md)
 - [CMake spec](cmake_spec.md)
 - [Null Pointer Checks](null_pointer_checks.md)
 - [Elektra Web Publish Subscribe](elektra_web_pubsub.md)

doc/decisions/binary.md

@@ -0,0 +1,42 @@
+# Binary
+
+## Problem
+
+binary
+
+- is the only metadata that allows more values (instead of making the validation stricter)
+- is the only API that modifies metadata
+- creates some inconsistencies in the API (e.g. `KEY_FLAG_RO_VALUE` is linked to `KEY_FLAG_RO_META`)
+
+## Constraints
+
+- simplify API
+
+## Assumptions
+
+byte-array values are a rarely used feature in configuration settings
+
+## Considered Alternatives
+
+- flag for indicating if a value is binary
+
+## Decision
+
+- make keys with untyped value per default (no assumption about type, i.e., byte-array)
+- all current types are not binary, so type = string is the way to indicate a string doesn't
+  - contain null bytes
+  - is not null (not only indicator of structure without value)
+  - uses some well-defined but unspecified text encoding (i.e. not necessarily ASCII or UTF-8)
+- remove binary functionality from keyNew keyVNew keyIsBinary keyIsString keyValue keyGetValueSize keyString keyGetString keySetString keyGetBinary keySetBinary
+- keySetRaw -> keySetValue
+
+## Rationale
+
+## Implications
+
+- metadata can also be binary
+- binary types would be possible (e.g. nullable-string)
+
+## Related Decisions
+
+## Notes

doc/decisions/bootstrap.md

@@ -5,18 +5,14 @@
 Currently, the default backend (default.ecf) will also be used for bootstrapping. There are two problems with this approach:
 
 1. Thus the default backend first will be read with parentKey `system:/elektra` and later with parentKey `system:/`, it needs to store absolute paths and thus won't work with most of the plugins (except dump).
-2. When `system` is large without mount points, everything is reread twice during bootstrapping.
+2. When `system:` is large without mount points, everything is reread twice during bootstrapping.
 
 ## Constraints
 
-- be compatible to mount points stored in `defaults.ecf`
-- nice migration phase
-- new setups should never bother about the compatibility mode
+- Bootstrap should be fast and not unnecessarily read large files
 
 ## Assumptions
 
-- Bootstrap should be fast and not unnecessarily read large files
-
 ## Considered Alternatives
 
 - Implement a hack so that `system:/elektra` is actually read as `system:/`. (Will not solve problem 2.)
@@ -34,22 +30,17 @@ The default backend reading `default.ecf` is only relevant as long as no root ba
 Algorithm:
 
 1. try to get system:/elektra using the file elektra.ecf (KDB_DB_INIT)
-2. if it works, mount the init backend to system:/elektra
+2. mount the init backend to system:/elektra
 
 ## Rationale
 
-- Solves both problems
-- Is fully compatible with any existing setup
-- People can decide if and how to migrate
-
 ## Implications
 
-- added scripts/upgrade-bootstrap
-
 ## Related Decisions
 
 ## Notes
 
+Added scripts/upgrade-bootstrap to migrate from previous setups
 to upgrade to new system, either:
 
 - touch /etc/kdb/elektra.ecf (loses old mount points)

doc/decisions/elektra_prefix.md

@@ -0,0 +1,35 @@
+# Elektra Prefix
+
+## Problem
+
+Some names, such as kdbOpen, keyNew are so generic that other libraries might also use them.
+
+## Constraints
+
+- In C such libraries, containing the same external identifier, cannot be used together.
+- The [C99 standard, section 5.2.4.1](http://www.open-std.org/jtc1/sc22/wg14/) gives following limit:
+  31 significant initial characters in an external identifier (each universal character name specifying a short identifier of 0000FFFF or less is considered 6 characters, each universal character name specifying a short identifier of 00010000 or more is considered 10 characters, and each extended source character is considered the same number of characters as the corresponding universal character name, if any)
+
+## Assumptions
+
+## Considered Alternatives
+
+- leave it as is
+- use macros to have short names for actually longer external identifiers
+
+## Decision
+
+Rename all functions to start with elektra.
+
+## Rationale
+
+- This makes it clear which functions come from Elektra.
+
+## Implications
+
+- Changes in basically every application and tool, but this is automated
+  with a refactoring tool @kodebach writes.
+
+## Related Decisions
+
+## Notes

doc/decisions/ensure.md

@@ -86,3 +86,6 @@ invocations. Contract `KeySet`s only contain `Key`s below
 - [Global Plugins](global_plugins.md)
 
 ## Notes
+
+- Issue [#2764](https://issues.libelektra.org/2764)
+- Implemented in #3651