Merge pull request #1903 from kodebach/hexnumber

Hexnumber

.gitignore

@@ -12,6 +12,7 @@
 
 #ignore all build directories of cmake
 build*/
+cmake-build*/
 
 #ignore ctags + gdb history files
 .ctags

cmake/Modules/LibAddMacros.cmake

@@ -554,7 +554,7 @@ function (generate_readme p) # rerun cmake when README.md is changed  also allow
 			contents
 			"${contents}")
 	string (REGEX
-		REPLACE "\"- +infos/author *= *([.@<>a-zéA-Z0-9 %_-]*)\\\\n\""
+		REPLACE "\"- +infos/author *= *([^\\\\]*)\\\\n\""
 			"keyNew(\"system/elektra/modules/${p}/infos/author\",\nKEY_VALUE, \"\\1\", KEY_END),"
 			contents
 			"${contents}")

doc/METADATA.ini

@@ -881,3 +881,10 @@ usedby/plugins= xerces
 type= string
 description= used to store the name of the xml file's original root element when mounting to a mountpoint which name doesn't correspond to the xml root element.
 	This metadata will be stored in the mountpoint key. When writing or exporting again, the stored name will be used for the root element of the corresponding xml document.
+
+[unit/base]
+type = dec hex
+default = dec
+usedby/plugins = hexnumber
+description = used to specify the base of an integer value. Currently only the hexnumber plugin supports this metadata. It converts any value marked as "hex" from
+    hexadecimal into decimal when the configuration is read, and back when it is written. The hexnumber plugin also ensures that a value marked as "hex" starts with "0x" or "0X".

doc/news/_preparation_next_release.md

@@ -79,7 +79,8 @@ We added even more functionality, which could not make it to the highlights:
 
 ## New Plugins
 
-- <<TODO>>
+- The plugin [hexnumber](https://www.libelektra.org/plugins/hexnumber) has been added. It can be used 
+  to convert hexadecimal values into decimal when read, and back to hexadecimal when written.
 - <<TODO>>
 - <<TODO>>
 

src/include/kdbhelper.h

@@ -41,7 +41,9 @@ char * elektraVFormat (const char * format, va_list arg_list);
 
 /* Compare */
 int elektraStrCmp (const char * s1, const char * s2);
+int elektraStrNCmp (const char * s1, const char * s2, size_t n);
 int elektraStrCaseCmp (const char * s1, const char * s2);
+int elektraStrNCaseCmp (const char * s1, const char * s2, size_t n);
 int elektraMemCaseCmp (const char * s1, const char * s2, size_t size);
 
 /* Len */

src/libs/elektra/internal.c

@@ -128,6 +128,23 @@ int elektraStrCmp (const char * s1, const char * s2)
 	return strcmp (s1, s2);
 }
 
+/**@brief Compare Strings up to a maximum length.
+ *
+ * @param s1 The first string to be compared
+ * @param s2 The second string to be compared
+ * @param n The maximum length to be compared
+ *
+ * @ingroup internal
+ * @return a negative number if s1 is less than s2
+ * @retval 0 if s1 matches s2
+ * @return a positive number if s1 is greater than s2
+ **/
+int elektraStrNCmp (const char * s1, const char * s2, size_t n)
+{
+	ELEKTRA_ASSERT (s1 != NULL && s2 != NULL, "Got null pointer s1: %p s2: %p", (void *) s1, (void *) s2);
+
+	return strncmp (s1, s2, n);
+}
 
 /**@brief Compare Strings ignoring case.
  *
@@ -145,6 +162,23 @@ int elektraStrCaseCmp (const char * s1, const char * s2)
 	return strcasecmp (s1, s2);
 }
 
+/**@brief Compare Strings ignoring case up to a maximum length.
+ *
+ * @param s1 The first string to be compared
+ * @param s2 The second string to be compared
+ * @param n The maximum length to be compared
+ *
+ * @ingroup internal
+ * @return a negative number if s1 is less than s2
+ * @retval 0 if s1 matches s2
+ * @return a positive number if s1 is greater than s2
+ **/
+int elektraStrNCaseCmp (const char * s1, const char * s2, size_t n)
+{
+	ELEKTRA_ASSERT (s1 != NULL && s2 != NULL, "Got null pointer s1: %p s2: %p", (void *) s1, (void *) s2);
+	return strncasecmp (s1, s2, n);
+}
+
 /**
  * @brief Compare two memory regions but make cmp chars uppercase before
  * comparison.

src/plugins/README.md

@@ -161,6 +161,7 @@ Transformations:
 - [keytometa](keytometa/) transforms keys to metadata
 - [rename](rename/) renames keys according to different rules
 - [boolean](boolean/) canonicalizes boolean keys
+- [hexnumber](hexnumber/) converts between hexadecimal and decimal
 
 Doing other stuff:
 

src/plugins/hexnumber/CMakeLists.txt

@@ -0,0 +1,3 @@
+include (LibAddMacros)
+
+add_plugin (hexnumber SOURCES hexnumber.h hexnumber.c LINK_ELEKTRA elektra-ease ADD_TEST TEST_README)

src/plugins/hexnumber/README.md

@@ -0,0 +1,97 @@
+- infos = Information about the hexnumber plugin is in keys below
+- infos/author = Klemens Böswirth <k.boeswirth+git@gmail.com>
+- infos/licence = BSD
+- infos/needs =
+- infos/provides = conv check
+- infos/recommends =
+- infos/placements = postgetstorage presetstorage
+- infos/status = nodep unittest maintained
+- infos/metadata = unit/base type
+- infos/ordering = type
+- infos/description = converts hexadecimal values into decimal and back
+
+## Introduction
+
+This plugin is used to read configuration files that use hexadecimal values. All "hex-values" (see below) will be 
+converted into decimal when Elektra reads values from the mounted file. When Elektra writes back to the file the converted values
+will be converted back and stored as before (`0X` will be replaced with `0x`).
+
+### What are "hex-values"?
+There are multiple ways you can signal to the hexnumber plugin, that a value should be converted:
+
+1. If a Key has the metadata `unit/base` set to `hex` it will always be interpreted as a hex-value. The plugin will also produce an error,
+   if the value contained in such a Key does not start with `0x` (or `0X`).
+2. If `unit/base` is not present and 
+    - the `type` metadata is set to one of the recognized integer-types (default: `byte`, `short`, `unsigned_short`, `long`, `unsigned_long`, 
+      `long_long`, `unsigned_long_long`) 
+    - AND the configuration value itself starts with `0x` (or `0X`) it will be interpreted as a hex-value.
+3. If forced conversion mode (`/force` plugin configuration, see below) is enabled all values starting with `0x` (or `0X`) are considered hex-values.
+
+## Configuration
+
+When mounting a backend with the hexnumber plugin, a few settings can be configured.
+
+1. To enable forced conversion mode set `/force` to any value. In forced conversion mode the plugin tries to convert **ALL** strings 
+   starting with `0x` (or `0X`) into decimal before passing the value on to the rest of Elektra. This can be useful for importing a 
+   configuration file that uses hexadecimal values into Elektra without writing a specification for the file.
+
+   NOTE: be careful when using this option, as any configuration value that contains invalid non-hexadecimal characters 
+         (i.e. does not match `0[xX][0-9A-Fa-f]+`) will result in an error.
+
+   ```
+   sudo kdb mount test.ecf /examples/hexnumber/forced hexnumber /force=1
+   ```
+
+2. The types recognized as integers can be configured. For this purpose specify all *additional* types you want to be considered for 
+   possible hexadecimal conversion as an Elektra array. All keys with a type from `/accept/types/#`, or one of the default types, will 
+   be converted to hexadecimal if the value starts with `0x` (or `0X`).
+
+   ```
+   sudo kdb mount test.ecf /examples/hexnumber/customtypes hexnumber /accept/types/#0=customint /accept/types/#1=othercustomint
+   ```
+
+## Usage & Example
+- To mount a simple backend that uses hexadecimal numbers, you can use:
+    ```sh
+    sudo kdb mount test.ecf user/tests/hexnumber hexnumber
+    ```
+
+- A few examples on how to use the plugin:
+    ```sh
+    # Example 1: read hex value
+    kdb set user/tests/hexnumber/hex 0x1F
+    kdb setmeta user/tests/hexnumber/hex type long
+    
+    kdb get user/tests/hexnumber/hex
+    #> 31
+    
+    # Example 2: decimal value not converted
+    kdb set user/tests/hexnumber/dec 26
+    kdb setmeta user/tests/hexnumber/dec type long
+    
+    kdb get user/tests/hexnumber/dec
+    #> 26
+    
+    # Example 3: string untouched
+    kdb set user/tests/hexnumber/string value
+    kdb setmeta user/tests/hexnumber/string type string
+    
+    kdb get user/tests/hexnumber/string
+    #> value
+    
+    # Example 4: read hex value with unit/base
+    kdb set user/tests/hexnumber/hex2 0xF
+    kdb setmeta user/tests/hexnumber/hex2 unit/base hex
+    
+    kdb get user/tests/hexnumber/hex2
+    #> 15
+    
+    # Undo changes
+    kdb rm -r user/tests/hexnumber
+    ```
+
+- To unmount the plugin use the following command:
+    ```sh
+    kdb umount user/tests/hexnumber
+    #>
+    ```