# Libchad
> Who said you ought to reinvent the wheel?

---

## Rationele
C libraries are hard to find; good libraries are even harder.
Libchad is a collection of quality, general-purpose, high-level libraries
aimed at modern C development.

## Compatibility
Libchad is standard C23.
Individual components might be compatible with older standards.

Headers must compile under C++17[^cpp].

Linux is the primary target OS[^target],
however compatibility with other UNIX-like operating systems should also be considered.
Compatibility with Windows is NOT a concern.

[^target]: This might be subject to change in the future,
particularly to BSD when the Linux finally becomes too tightly integrated with cancerware,
such as Rust and Systemd.

[^cpp]: This requirement added for practicality.
It might be subject to change specifically
if some meta-programming based OOP solution for C
gains appropriate maturity.

## Contents

> [!NOTE] `chad.h` includes all Chad libraries.

### IO

| Lib         | Description |
| :---        | :---------- |
| dictate.h   | Über-printer. |
| plumblism.h | PBMplus (PNM) image IO. |
// https://github.com/ClecioJung/ini (slight renaming and _Generic)
// https://github.com/an-dr/microlog

### Datastructures

| Lib       | Description |
| :---      | :---------- |
| sds.h     | Dynamic strings. |
| haste.h   | Type-safe generic containers optimized single threaded speed. |
| strlist.h | String lists. |

### Memory

| Lib            | Description |
| :---           | :---------- |
| memory-units.h | Memory unit macros. |
| zone.h         | Zone allocator. |
// arena allocator

### Ported functionality

| Lib           | Lang  | Description |
| :---          | :---: | :---------- |
| qx.h          | Perl  | Capture output of exec. |
| slurp.h       | Perl  | Simple reading/writing/modifying of complete files. |
| remove\_all.h | C++   | Remove a directory recursively. |

---

## Experimental
The mainline chad libraries are considered to have a stable API.
They might get extended, but are not expected to change.
Experimental libraries on the other hand are volatile.

| Lib    | Description |
| :---   | :---------- |
| bits.h | Various miscellaneous functionalities. |

## Criteria
* A clear way in which the functionality can be described as.
(e.g.: "generic datastructures" - good; "roguelike stuff" - bad)
* Clean and simple interface which can be learned under a few minutes.
Complexity has its place: within its own library.
* Must be amalgamable into a single header.
* No project-namespacing.
* The top of the headers must have a *description comment*.
* The *description comment* must be followed by declarations.
* License comments may not take up more than 3 lines (worst case being a title, the license body and the list of people holding the copyright).
* Each library must come with a `man(1)` compatible manual.

## Recommendations
Some subjects are outside of the scope of this project,
but not outside of its interest.
For such cases, a recommendations table exists.
Any item on the recommendations table have been throughly reviewed
and is believed to be the best-of-its-kind as of now.
Consequently, only one item per subject should be provided
and a clean-cut predicate to choose between items of similar subjects.

| Library | Subject | Description |
| :------ | :------ | :---------- |
| XXX | XXX | XXX |

## Todo
* peru is nice as a concept, but 1) depends on py-yaml, 2) yaml makes make me vomit from my eyes
* code
```sh
    file filesystem.h {
        int touch_file(const char * p);
        int touch_directory(const char * p);
        int touch(const char * p);  // wrapper based on whether the last char is '/'

        int copy_file(const char * s, const char * d);
        int copy(const char * s, const char * d);
        int copy_ex(const char * s, const char * d, int flags);

        int remove(const char * p);
        int remove_all(const char * p);

        int rename(const char * s, const char * d);
    }
    tree chad/
        file nargs.h { // for narg hack functions?
            #define coalesce_env() // char * _coalesce_env(char * mydefault, size_t argc, ...)
            // maybe just coalesce()? that means every argument is eval-ed; maybe both
            #define max()
            #define min()
            // all(), any() 
            // ?! i cant think of a single instance where its preferable over plain logic,
            //  but it would be consistent
        }
    # something addressing math.h
    #  gcd(), lcm(), sq() /*square, after ino*/
    #
    # the linux kernel has a bunch of small, high quality utilities,
    #  these should be inspected
    # * minmax.h looks good; i wonder if it can be made N-arg
    #    in_range does not with in _there_
    # * array_size.h looks good
    # * DIV_ROUND_UP
    # * base64.h
    # * crc?
    # * glob.h
    #
    # Strings:
    #   trim() and pad() even tho its a meme
    #   slugify
    #   reverse
    #   case conversions
```

The following items should be considered to be added to libchad, in some way or another:
+ [ ] Xandard
+ [ ] Plan9 (e.g. libutf)
+ [ ] [https://github.com/EasyMem/easy_memory](https://github.com/EasyMem/easy_memory)
+ [ ] [https://github.com/tarantula-org/camelot](https://github.com/tarantula-org/camelot)
+ [ ] [https://www.gnu.org/software/gnulib/manual/html_node/index.html](https://www.gnu.org/software/gnulib/manual/html_node/index.html)
+ [ ] [https://github.com/arp242/toml-c](https://github.com/arp242/toml-c)
+ [ ] [https://github.com/wolkykim/qlibc](https://github.com/wolkykim/qlibc) (qencode, qcount)
+ [ ] [https://github.com/swansontec/map-macro](https://github.com/swansontec/map-macro)
+ [ ] [https://www.boost.org/doc/libs/latest/libs/preprocessor/doc/index.html](https://www.boost.org/doc/libs/latest/libs/preprocessor/doc/index.html)
+ [ ] [https://github.com/ClecioJung/ini](https://github.com/ClecioJung/ini)
+ [ ] [https://github.com/arp242/toml-c](https://github.com/arp242/toml-c)
+ [ ] [https://git.enlightenment.org/enlightenment/efl](https://git.enlightenment.org/enlightenment/efl)
+ [ ] [https://github.com/scottt/debugbreak.git](https://github.com/scottt/debugbreak.git) (since the compatibility is a nightmare, maybe just provide `breakpoint()`, which is empty, but kept from being optimized away)
+ [ ] [https://gitlab.freedesktop.org/libbsd/](https://gitlab.freedesktop.org/libbsd/) (vis)