From c1e776064dfdfed58ac92f70f7be1390982f0c1c Mon Sep 17 00:00:00 2001
From: TennesseeTrash <vitosoukup@gmail.com>
Date: Mon, 9 Jun 2025 01:42:20 +0200
Subject: [PATCH] [General] Add a more proper description

---
 README.md | 107 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 106 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5ce7791..0552635 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,108 @@
 # Garbage
 
-A collection of various single-header libraries of questionable quality.
\ No newline at end of file
+A collection of various single-header libraries of questionable quality.
+
+## Usage
+
+To use these libraries (please don't), just add them into your project's include path.
+Ideally, use CMake with FetchContent pinned to a specific commit hash so you don't encounter
+nasty surprises when the libraries update.
+
+```cmake
+include(FetchContent)
+
+FetchContent_Declare(
+    Garbage
+    GIT_REPOSITORY https://code.3011.io/TennesseeTrash/Garbage
+    GIT_TAG        72f02ff856ddfd1b817d4f95096ec1be0ed11a49
+)
+
+FetchContent_MakeAvailable(
+    Garbage
+)
+```
+
+Once you've added the `Include` directory into your include path, you can use the headers you need,
+e.g.
+```cpp
+#include <Garbage/Base64.hpp>
+
+// Now you can use
+Garbage::Base64::Decode(/* some base64 string */);
+```
+
+## Base64
+
+A very simple library composed of 3 functions in the `Garbage::Base64` namespace.
+
+- `Encode()` takes a `std::span<std::uint8_t>` (i.e. an array of bytes), and produces a
+  padded Base64 encoded string out of it.
+- `Decode()` takes an encoded `std::string_view`, and converts it into an array of bytes
+  (specifically a `std::vector<std::uint8_t>`).
+- `Validate()` performs validation of an untrusted `std::string_view`. This is necessary
+  because `Decode()` does not do any checking and running it on unverified data is
+  dangerous. This function is not completely robust, but it is good enough to make sure
+  the `Decode()` call is safe.
+
+## SimpleConf
+
+A small config file library. Provides a `Garbage::SimpleConf` class that reads files
+with key-value pairs. This library makes use of exceptions, it will throw `Garbage::SimpleConfError`
+when an error is encountered. These exceptions inerit from `std::exception`, so using those to catch
+them works fine.
+
+```cpp
+///////////////////////////////////////////////////////////////////////////////
+// INIT
+
+// Read a file from disk
+Garbage::SimpleConf config(std::filesystem::path(/*path to the config*/));
+
+// Use an externally provided string
+std::string rawConfig = /* whatever procedure to obtain a string */;
+Garbage::SimpleConf config(std::move(rawConfig));
+
+///////////////////////////////////////////////////////////////////////////////
+// GETTING VALUES
+
+// Optional values
+
+// Get a std::optional
+auto value = config.GetOptional<std::string>("SomeKey");
+// Get a default value
+int value = config.Get<int>("SomeKey", 0 /* Optional default value */);
+
+// Required values
+using Required = Garbage::SimpleConf::Required;
+int value = config.Get<int, Required>("SomeKey");
+```
+
+The config files are structured such that a single line contains a key-value pair separated by a `=`
+character.
+Some specifics:
+- Leading and trailing whitespace is removed from both keys and values.
+- Whitespace is is allowed inside both keys and values.
+- Values may be empty.
+- The `#` character denotes the start of a comment, everything after (and including)
+  this character is ignored until the end of the line.
+
+Example:
+```conf
+# Simplest scenario
+SomeKey=SomeValue
+
+# Also works
+  SomeKey = SomeValue
+
+# Also supported, but note that the key is now "Some Key"
+Some Key = Some Value
+
+Comments = After # The pair are also fine
+
+# Also fine
+KeyOnly=
+```
+
+## SQLite
+
+WIP