<commit_before># DESIGN

This document describes the design of Elektra's C-API and provides hints for
binding writers. It is not aimed at plugin writers, since it does not
talk about the implementation details of Elektra.

Elektra [aims](GOALS.md) to fulfill the following design principles:

1. To make the API futureproof so that it can remain compatible and stable
   over a long period of time,
2. to make it hard to use the API the wrong way by making it simple & robust, and
3. to make the API easy to use for programmers reading and writing
   configuration.

The C-API is suitable to be reimplemented, also in non-C-languages, like Rust.
Elektra provides a full blown architecture to support configuring systems, and
the C-API is the core of this endeavour.

## Data Structures

The `Key`, `KeySet` and `KDB` data structures are defined in
`kdbprivate.h` to allow ABI compatibility.
This means, it is not possible to put one of Elektra’s data structures
on the stack. You must use the memory management facilities mentioned
in the next section.

## Memory Management

Elektra provides functions that create and free data.
For example after you call:

```c
KDB * kdbOpen();
```

you need to use:

```c
int kdbClose(KDB *handle);
```

to get rid of the resources again. The second function may also shut
down connections. Therefore it must be called before the end of a program.

```c
Key *keyNew(const char *keyName, ...);
int keyDel(Key *key);

KeySet *ksNew(int alloc, ...);
int ksDel(KeySet *ks);
```

In the above pairs, the first function reserves the necessary amount
of memory. The second function frees the allocated data segment. There
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

```c
const char *keyString(const Key *key);
```

returns a string. You are not allowed to change the returned string.
The function

```c
ssize_t keyGetValueSize(const Key *key);<commit_msg>ncorporate @muskater's suggestions<commit_after># DESIGN

This document describes the design of Elektra's C-API and provides hints for
binding writers. It is not aimed at plugin writers, since it does not
talk about the implementation details of Elektra.

Elektra [aims](GOALS.md) to fulfill the following design principles:

1. To make the API future-proof so that it can remain compatible and stable
   over a long period of time,
2. to make it hard to use the API the wrong way by making it simple & robust, and
3. to make the API easy to use for programmers reading and writing
   configuration.

The C-API is suitable to be reimplemented, also in non-C-languages, like Rust.
Elektra provides a full blown architecture to support configuring systems, and
the C-API is the core of this endeavour.

## Data Structures

The `Key`, `KeySet` and `KDB` data structures are defined in
`kdbprivate.h` to allow ABI compatibility.
This means, it is not possible to put one of Elektra’s data structures
on the stack. You must use the memory management facilities mentioned
in the next section.

## Memory Management

Elektra provides functions that create and free data.
For example after you call:

```c
KDB * kdbOpen();
```

you need to use:

```c
int kdbClose(KDB *handle);
```

to get rid of the resources again. The second function may also shut
down connections. Therefore, it must be called before the end of a program.

```c
Key *keyNew(const char *keyName, ...);
int keyDel(Key *key);

KeySet *ksNew(int alloc, ...);
int ksDel(KeySet *ks);
```

In the above pairs, the first function reserves the necessary amount
of memory. The second function frees the allocated data segment. There
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

```c
const char *keyString(const Key *key);
```

returns a string. You are not allowed to change the returned string.
The function

```c
ssize_t keyGetValueSize(const Key *key);
{'fraction_non_alphanumeric': 0.06616126809097174, 'fraction_numerical': 0.002297266253158741, 'mean_word_length': 4.322738386308068, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '2429009', 'n_tokens_mistral': 1235, 'n_tokens_neox': 1186, 'n_words': 679}