🦭seallib🦭

A modular and tiny C++20 powered library collection of random stuff I've needed for other projects.

---

Table of Contents

• Installation & Integration
• Build Options
• Modules
  • Logging
  • Assert
  • Events
  • VFS
• Running tests

Installation & Integration

1. Requirements

• Compiler: A C++20 compliant compiler.
• Build System: CMake 4.1.0 or higher.

2. Integration via CMake

Option A: Using FetchContent (Recommended)

You can pull the library directly into your project from the git repository. Add this to your CMakeLists.txt:

include(FetchContent)

FetchContent_Declare(
    seallib
    GIT_REPOSITORY https://git.neru.rip/neru/seallib.git
    GIT_TAG main # or a specific commit hash
)

# Enable the modules you want before making it available
set(SEALLIB_LOG ON)
set(SEALLIB_ASSERT OFF)

FetchContent_MakeAvailable(seallib)

target_link_libraries(your_project PRIVATE seallib)

Option B: Local Path

If you have the library downloaded locally:

# Enable the modules you want before adding it
set(SEALLIB_LOG ON)
set(SEALLIB_ASSERT OFF)

add_subdirectory(path/to/seallib)

target_link_libraries(your_project PRIVATE seallib)

---

Build Options

Toggle features by setting these variables to ON or OFF in your CMake configuration.

Option	Description	Default
SEALLIB_ASSERT	Enable Assertion utility	OFF
SEALLIB_EVENTS	Enable Event Dispatcher	OFF
SEALLIB_LOG	Enable Logging Framework	OFF
SEALLIB_VFS	Enable Virtual File System	OFF
SEALLIB_TEST	Build the test project	OFF

---

Modules

1. Logging

The Log module uses a Sink architecture. You create a Logger, attach an ILogSink, and log messages using std::format syntax.

Example

#include <seallib/log.h>
#include <iostream>

using namespace seallib;

class ConsoleSink : public ILogSink {
public:
    void receiveLog(LogType type, std::string_view loggerName, std::string_view message) override {
        std::cout << getLogTypeColor(type) << "[" << getLogTypeName(type) << "] "
                  << "[" << loggerName << "] " 
                  << message << "\x1b[0m" << std::endl;
    }
};

int main() {
    Logger logger("MainApp");
    logger.addSink(std::make_shared<ConsoleSink>());

    logger.info("Application started with version {}", 1.0);
    logger.error("Failed to load config: {}", "file_not_found.json");

    return 0;
}

2. Assert

The assert module provides diagnostic macros made to trap critical logic failures.

Macros and their behavior

Macro	Debug Mode (_DEBUG)	Release Mode
ASSERT(cond, msg)	Evaluates cond. If false, logs the error location, pops up an interactive modal error box, drops a debugger breakpoint trap, and calls std::exit.	Evaluates to a compiler optimization hint informing the optimizer that cond is always true.
PANIC(msg)	Logs the error, displays an interactive modal error box, breaks execution, and terminates.	Logs the error, displays an interactive modal error box, breaks execution, and terminates. Always halts execution.

Example

#include <seallib/assert.h>

void processSystemData(void* dataPtr, int size) {
    // 1. Defensively check states that should literally be impossible in a valid run
    ASSERT(dataPtr != nullptr, "Managed data pointer cannot be null during processing pipe");
    
    // 2. Asserts behave as optimizer hints in Release mode. 
    // The compiler now optimizes this function knowing 'size' can never be less than zero.
    ASSERT(size >= 0, "Buffer stream size constraint violation");

    if (size == 0) {
        return; // Valid empty state
    }

    // Processing logic...
}

void processNetworkPacket(int packetId) {
    switch (packetId) {
        case 1: /* Handle read */ break;
        case 2: /* Handle write */ break;
        default:
            // 3. Use PANIC for unrecoverable structural states that must crash 
            // the software immediately in both Debug and Release builds.
            PANIC("Critical Error: Received completely unhandled or corrupted packet opcode");
            break;
    }
}

int main() {
    // Fails in debug: triggers a modal error window detailing the file and line number
    processSystemData(nullptr, -1); 

    return 0;
}

3. Events

The Events module provides a thread and type safe signal/slot mechanism. It allows you to define custom events with any number of parameters and subscribe to them using callbacks.

Example

#include <seallib/event.h>
#include <iostream>

using namespace seallib;

// Define an event that takes an int and a string
Event<int, std::string> OnUserLogin;

void onLogin(int id, std::string name) {
    std::cout << "User " << name << " (ID: " << id << ") logged in!" << std::endl;
}

int main() {
    // 1. Subscribe to the event
    auto connection = OnUserLogin.addListener(onLogin);

    // 2. Add a lambda listener
    OnUserLogin.addListener([](int id, auto name) {
        std::clog << "[Log] Login detected for ID: " << id << std::endl;
    });

    // 3. Trigger the event
    OnUserLogin.run(42, "SomeUser");

    // 4. Remove a listener when no longer needed
    OnUserLogin.removeListener(connection);

    return 0;
}

4. VFS

The VFS (Virtual File System) module provides a unified interface for file operations by mapping virtual paths to user defined providers.

Implementing a file provider

To create a new storage backend (e.g., a zip loader, encrypted volume, etc), you must inherit from IFileProvider.

Example provider implementation

#include <seallib/vfs.h>

using namespace seallib;

class MyCustomProvider : public IFileProvider {
public:
    // checks if file exists
    bool exists(const std::string& path) const override {
        /*
            implementation logic here
        */
        return true; 
    }

    // loads data from provider to outBuffer
    VFSResult readFile(const std::string& path, FileBuffer& outBuffer) const override {
        /* 
           1. locate the file in your system.
           2. if not found, return VFSResult::FileNotFound.
           3. allocate memory: outBuffer.data = std::make_unique<uint8_t[]>(size);
           4. copy data into outBuffer.data and set outBuffer.size = size;
        */
        return VFSResult::Success;
    }

    // write data from a buffer to your provider
    VFSResult writeFile(const std::string& path, const FileBuffer& buffer) override {
        /* 
           VFS ensures 'buffer' is valid (data != nullptr) before calling this.
           return VFSResult::AccessDenied if your provider is read-only or if that path shouldn't be written to
        */
        return VFSResult::Success;
    }

    // generic file management operations
    VFSResult deleteFile(const std::string& path) override { return VFSResult::Success; }
    VFSResult createDirectory(const std::string& path) override { return VFSResult::Success; }

    // list all files and subdirectories within a given path
    std::vector<std::string> listDirectory(const std::string& path) const override {
        // note: directories should ideally end with a '/' for clarity
        return { "file1", "file2", "file3" };
    }

    // optional: return a name for debugging/logging
    std::string getProviderName() const override { return "MyCustomProvider"; }
};

Example provider usage

#include <seallib/vfs.h>

using namespace seallib;

int main() {
    VirtualFileSystem vfs;

    /*
        mount a disk provider to the virtual "assets" folder
        higher priority (10 in this case) means this mount is checked before others
    */
    vfs.mount("/assets", std::make_unique<DiskFileProvider>("./data"), 10);

    // reading a file (Paths are automatically normalized to remove '../' etc.)
    FileBuffer buffer;
    if (vfs.readFile("/assets/somefile.bin", buffer) == VFSResult::Success) {
        std::string rawData = buffer.toString();
    }

    return 0;
}

---

Running tests

Windows (PowerShell + Visual Studio)

A script is provided to automate generation and open the solution in Visual Studio:

./create-test.ps1

Cross-Platform (CLI)

To build and run manually from the terminal:

mkdir build && cd build
cmake .. -DSEALLIB_TEST=ON
cmake --build .
./seallib-test

License

MIT