Skip to content
Permalink
Browse files

Merge pull request #3038 from PhilippGackstatter/remove_keyrel

Remove keyRel and keyRel2
  • Loading branch information...
markus2330 committed Oct 9, 2019
2 parents 39c3824 + 9de4226 commit 91e5808010e7affddcce6bca86296f1da6f84ae8
@@ -43,8 +43,8 @@ If two keys start with the same key names, but one key name continues
after a slash, this key is **below** the other and is called a
_subkey_. For example `user/sw/apps/abc/current` is a subkey of the
key `user/sw/apps`. The key is not directly below but, for example,
`user/sw/apps/abc` is. `keyRel()` implements a way to decide the relation
between two keys.
`user/sw/apps/abc` is. Various functions in `keytest` implement
ways to determine the relationship between two keys.

## Conventions

@@ -51,7 +51,8 @@ user/sw/kde/kicker/#0/current/preferred_applications/#0
.IP "" 0
.
.P
The slash (\fB/\fR) separates key names and structures them hierarchically\. If two keys start with the same key names, but one key name continues after a slash, this key is \fBbelow\fR the other and is called a \fIsubkey\fR\. For example \fBuser/sw/apps/abc/current\fR is a subkey of the key \fBuser/sw/apps\fR\. The key is not directly below but, for example, \fBuser/sw/apps/abc\fR is\. \fBkeyRel()\fR implements a way to decide the relation between two keys\.
The slash (\fB/\fR) separates key names and structures them hierarchically\. If two keys start with the same key names, but one key name continues after a slash, this key is \fBbelow\fR the other and is called a \fIsubkey\fR\. For example \fBuser/sw/apps/abc/current\fR is a subkey of the key \fBuser/sw/apps\fR\. The key is not directly below but, for example, \fBuser/sw/apps/abc\fR is\. Various functions in \fBkeytest\fR implement
ways to determine the relationship between two keys\.
.
.SH "Conventions"
For computers Elektra would work without any conventions, because it is possible to rename keys with plugins and link and transform any key\-value to any other key\-value\. Obviously, for humans such chaos would be confusing and harder to use, thus we encourage everyone to use the following conventions:
@@ -65,6 +65,7 @@ The following section lists news about the [modules](https://www.libelektra.org/
- `struct`. _(Markus Raab, René Schwaiger)_
- We unified the name of the config check function of the plugins to `nameOfPluginCheckConf`. Before this update some plugins used the name `nameOfPluginCheckConfig` instead. _(René Schwaiger)_
- Fixed some typos and links in the documentation and add new iterate example. _(Philipp Gackstatter)_
- We removed `keyRel` and `keyRel2` since it can be easily replaced by other existing functions. _(Philipp Gackstatter)_

### Camel

@@ -67,7 +67,6 @@ Remove/Refactor/Rename obsolete/not needed methods:
- keyNextMeta
- keyCurrentMeta
- keyCmp
- keyRel
- keyNeedSync
- keyIsBelow
- keyIsBelowOrSame
@@ -69,8 +69,6 @@
/* Methods for Making Tests */
int keyCmp(Pointer k1, Pointer k2);

int keyRel(Pointer k1, Pointer k2);

int keyNeedSync(Pointer key);

int keyIsBelow(Pointer key, Pointer check);
@@ -519,19 +519,6 @@ public int cmp(final Key other) {
return Elektra.INSTANCE.keyCmp(get(), other.get());
}

/**
* Helper function to check for relation between keys
*
* @param other Other Key object that is used in relation check
* @return 0 if other is equal to this; > 0 if other is sub-key of this key; < 0 otherwise or in case of an error
*/
public int rel(final Key other) {
if (other == null) {
throw new IllegalArgumentException("other should be a key, not null");
}
return Elektra.INSTANCE.keyRel(get(), other.get());
}

/**
* Helper function to check if synchronization is necessary
*
@@ -224,17 +224,6 @@ public void test_keyCompare_shouldPass() {
assertEquals(1, key2.cmp(key));
}

@Test
public void test_keyRelation_shouldPass() {
final Key key = Key.create(KEY_10_NAME, KEY_10_VALUE);
final Key key2 = Key.create(KEY_11_NAME, KEY_11_VALUE);
final Key key3 = Key.create(KEY_12_NAME, KEY_12_VALUE);
assertEquals(0, key.rel(key));
assertEquals(1, key.rel(key2));
assertEquals(2, key.rel(key3));
assertEquals(1, key2.rel(key3));
}

@Test
public void test_keyIsBelow_shouldPass() {
final Key key = Key.create(KEY_10_NAME, KEY_10_VALUE);
@@ -158,7 +158,6 @@ ssize_t keySetMeta(Key *key, const char* metaName,

/* Methods for Making Tests */
int keyCmp(const Key *k1, const Key *k2);
int keyRel (const Key *k1, const Key *k2);

int keyNeedSync(const Key *key);

@@ -68,27 +68,6 @@ KeySet * elektraKeyGetMetaKeySet (const Key * key);
Key * ksPrev (KeySet * ks);
Key * ksPopAtCursor (KeySet * ks, cursor_t c);


typedef enum
{
ELEKTRA_REL_BELOW_SAME_NS = 1 << 0, // Below Same Namespace, cascading namespace matches only cascading namespace
ELEKTRA_REL_BELOW_IGNORE_NS = 1 << 1, // Below Ignore Namespace, namespaces are ignored
ELEKTRA_REL_BELOW_CASCADING_NS = 1 << 2, // Below (allow) Cascading Namespace, cascading namespace matches all namespaces
ELEKTRA_REL_DIRECT_BELOW_SAME_NS = 1 << 3, // Direct Below Same Namespace
ELEKTRA_REL_DIRECT_BELOW_IGNORE_NS = 1 << 4, // Direct Below Ignore Namespace
ELEKTRA_REL_DIRECT_BELOW_CASCADING_NS = 1 << 5, // Direct Below (allow) Cascading Namespace
ELEKTRA_REL_SILBLING_SAME_NS = 1 << 6, // Sibling Same Namespace
ELEKTRA_REL_SILBLING_IGNORE_NS = 1 << 7, // Sibling Ignore Namespace
ELEKTRA_REL_SILBLING_CASCADING_NS = 1 << 8, // Sibling (allow) Cascading Namespace
ELEKTRA_REL_NEPHEW_SAME_NS = 1 << 9, // Nephew Same Namespace
ELEKTRA_REL_NEPHEW_IGNORE_NS = 1 << 10, // Nephew Ignore Namespace
ELEKTRA_REL_NEPHEW_CASCADING_NS = 1 << 11, // Nephew (allow) Cascading Namespace
} KeyRelType;

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
}
}
@@ -187,7 +187,7 @@ Backend * backendOpen (KeySet * elektraConfig, KeySet * modules, KeySet * global

while ((cur = ksNext (elektraConfig)) != 0)
{
if (keyRel (root, cur) == 1)
if (keyIsDirectlyBelow (root, cur) == 1)
{
// direct below root key
KeySet * cut = ksCut (elektraConfig, cur);
@@ -653,11 +653,6 @@ static int keyCompareByNameOwnerCase (const void * p1, const void * p2)
*
* @note the owner will only be used if the names are equal.
*
* Often is enough to know if the other key is
* less then or greater than the other one.
* But Sometimes you need more precise information,
* see keyRel().
*
* Given any Keys k1 and k2 constructed with keyNew(), following
* equation hold true:
*
@@ -348,149 +348,6 @@ int keyIsDirectlyBelow (const Key * key, const Key * check)
}


/**
* Information about the relation in the hierarchy between
* two keys.
*
* Unlike keyCmp() the number gives information
* about hierarchical information.
*
*
* - If the keys are the same 0 is returned.
* So it is the key itself.
@verbatim
user/key
user/key
@endverbatim
*
*@code
keySetName (key, "user/key/folder");
keySetName (check, "user/key/folder");
succeed_if (keyRel (key, check) == 0, "should be same");
*@endcode
*
* @note this relation can be checked with keyCmp() too.
*
*
* - If the key is direct below the other one 1 is returned.
* That means that, in terms of hierarchy, no other key is
* between them - it is a direct child.
@verbatim
user/key/folder
user/key/folder/child
@endverbatim
*
*@code
keySetName (key, "user/key/folder");
keySetName (check, "user/key/folder/child");
succeed_if (keyRel (key, check) == 1, "should be direct below");
*@endcode
*
*
* - If the key is below the other one, but not directly 2 is returned.
* This is also called grand-child.
@verbatim
user/key/folder
user/key/folder/any/depth/deeper/grand-child
@endverbatim
*
*
*@code
keySetName (key, "user/key/folder");
keySetName (check, "user/key/folder/any/depth/deeper/grand-child");
succeed_if (keyRel (key, check) >= 2, "should be below (but not direct)");
succeed_if (keyRel (key, check) > 0, "should be below");
succeed_if (keyRel (key, check) >= 0, "should be the same or below");
*@endcode
*
*
* - If an invalid or null ptr key is passed, -1 is returned
*
*
* - If the keys have no relations, but are not invalid, -2 is returned.
*
*
* - If the keys are in the same hierarchy, a value smaller then -2 is returned.
* It means that the key is not below.
@verbatim
user/key/myself
user/key/sibling
@endverbatim
*
* @code
keySetName (key, "user/key/folder");
keySetName (check, "user/notsame/folder");
succeed_if (keyRel (key, check) < -2, "key is not below, but same namespace");
* @endcode
*
* @code
* @endcode
*
*
* TODO Below is an idea how it could be extended:
* It could continue the search into the other direction
* if any (grand-)parents are equal.
*
* - If the keys are direct below a key which is next to the key, -2 is returned.
* This is also called nephew. (TODO not implemented)
* @verbatim
user/key/myself
user/key/sibling
@endverbatim
*
* - If the keys are direct below a key which is next to the key, -2 is returned.
* This is also called nephew. (TODO not implemented)
* @verbatim
user/key/myself
user/key/sibling/nephew
@endverbatim
*
* - If the keys are below a key which is next to the key, -3 is returned.
* This is also called grand-nephew. (TODO not implemented)
@verbatim
user/key/myself
user/key/sibling/any/depth/deeper/grand-nephew
@endverbatim
*
* The same holds true for the other direction, but with negative values.
* For no relation INT_MIN is returned.
*
* @note to check if the keys are the same, you must use
* keyCmp() == 0!
* keyRel() does not give you the information if it did not
* find a relation or if it is the same key.
*
* @return depending on the relation
* @retval 2 if below
* @retval 1 if direct below
* @retval 0 if the same
* @retval -1 on null or invalid keys
* @retval -2 if none of any other relation
* @retval -3 if same hierarchy (none of those below)
* @retval -4 if sibling (in same hierarchy)
* @retval -5 if nephew (in same hierarchy)
*
* @param key the key object to work with
* @param check the second key object to check the relation with
* @ingroup keytest
*/
int keyRel (const Key * key, const Key * check)
{
if (!key || !check) return -1;
if (!key->key || !check->key) return -1;

if (!keyCmp (key, check)) return 0;
if (keyIsDirectlyBelow (key, check)) return 1;
if (keyIsBelow (key, check)) return 2;
if (keyIsUser (key) && keyIsUser (check)) return -3;
if (keyIsSystem (key) && keyIsSystem (check)) return -3;
// if (keyIsSibling(key, check)) return -4;
// if (keyIsNephew(key, check)) return -5;

return -2;
}


/**
* Check whether a key is inactive.
*
@@ -61,7 +61,7 @@ int mountOpen (KDB * kdb, KeySet * config, KeySet * modules, Key * errorKey)
int ret = 0;
while ((cur = ksNext (config)) != 0)
{
if (keyRel (root, cur) == 1)
if (keyIsDirectlyBelow (root, cur) == 1)
{
KeySet * cut = ksCut (config, cur);
Backend * backend = backendOpen (cut, modules, kdb->global, errorKey);
@@ -398,7 +398,7 @@ int mountGlobals (KDB * kdb, KeySet * keys, KeySet * modules, Key * errorKey)
while ((cur = ksNext (global)) != NULL)
{
// the cutpoints for the plugin configs are always directly below the "root", ignore everything else
if (keyRel (root, cur) != 1) continue;
if (keyIsDirectlyBelow (root, cur) != 1) continue;

char * placement = elektraStrDup (keyBaseName (cur));

@@ -432,7 +432,7 @@ int mountGlobals (KDB * kdb, KeySet * keys, KeySet * modules, Key * errorKey)
Key * curSubPosition;
while ((curSubPosition = ksNext (subPositions)) != NULL)
{
if (keyRel (placementKey, curSubPosition) != 1) continue;
if (keyIsDirectlyBelow (placementKey, curSubPosition) != 1) continue;
const char * subPlacement = keyBaseName (curSubPosition);

for (GlobalpluginSubPositions j = 0; j < NR_GLOBAL_SUBPOSITIONS; ++j)
@@ -155,7 +155,7 @@ int elektraProcessPlugins (Plugin ** plugins, KeySet * modules, KeySet * referen

while ((cur = ksNext (config)) != 0)
{
if (keyRel (root, cur) == 1)
if (keyIsDirectlyBelow (root, cur) == 1)
{
char * pluginName = 0;
char * referenceName = 0;
@@ -329,15 +329,16 @@ int splitBuildup (Split * split, KDB * kdb, Key * parentKey)
/* Catch all: add all mountpoints */
splitAppend (split, kdb->split->handles[i], keyDup (kdb->split->parents[i]), kdb->split->syncbits[i]);
}
else if (backend == kdb->split->handles[i] && keyRel (kdb->split->parents[i], parentKey) >= 0)
else if (backend == kdb->split->handles[i] &&
(keyCmp (kdb->split->parents[i], parentKey) == 0 || keyIsBelow (kdb->split->parents[i], parentKey) == 1))
{
#if DEBUG && VERBOSE
printf (" exa add %s\n", keyName (kdb->split->parents[i]));
#endif
/* parentKey is exactly in this backend, so add it! */
splitAppend (split, kdb->split->handles[i], keyDup (kdb->split->parents[i]), kdb->split->syncbits[i]);
}
else if (keyRel (parentKey, kdb->split->parents[i]) >= 0)
else if (keyCmp (parentKey, kdb->split->parents[i]) == 0 || keyIsBelow (parentKey, kdb->split->parents[i]) == 1)
{
#if DEBUG && VERBOSE
printf (" rel add %s\n", keyName (kdb->split->parents[i]));
@@ -82,7 +82,6 @@ libelektra_0.8 {
keyNeedSync;
keyNew;
keyNextMeta;
keyRel;
keyRewindMeta;
keySetBaseName;
keySetBinary;

0 comments on commit 91e5808

Please sign in to comment.
You can’t perform that action at this time.