Presheaf Library
================

> WARNING: This library is currently in a very volatile state. Breaking changes will happen all the
> time until I think the API is good enough.

This is a core C++ library that I use as a base layer across all of my projects as an alternative
to the STL. It's written in C++20 and its only external dependencies are libc and a few OS headers.

The code is written with simplicity and performance in mind. There is no use of exceptions,
inheritance, smart pointers, etc. The goal is for this library to stand the test of time. For more
information about the design decisions, check the STYLE_GUIDE.

Building
========

Compilers that are ensured to work are: Clang, GCC, MSVC.

Ad-Hoc Approach
---------------

The library has a bundled compilation unit src/presheaf.cpp which may be used if you wish to
compile as a unity build. This can be as simple as, e.g.:

1. Build object files without linking:

                 clang++ -c -std=c++20 -Iinclude src/presheaf.cpp -o presheaf.o

2. Archive object files into a library:

                           llvm-ar rc libpresheaf.a presheaf.o

Yet another ad-hoc solution would be to directly embed the library into your codebase using both of
the bundle files src/presheaf.cpp and src/presheaf.hpp, feel free to do as you wish.

Custom Build System
-------------------

The library comes with its custom build system build.lua, which will manage the project with many
custom options. An usage example would be:

        lua build.lua -release -clang -dll -- -DPSH_CHECK_BOUNDS -fsanitize=undefined

where you are building the release version of Presheaf as a DLL (or shared object if on Unix)
using Clang. Additionally you are also activating the UB sanitizer for the build, and bounds checking
assertions. The script will make sure to print out the final invoked command for the compilation, so
no mysteries arise in the build process.

For more information, please run the script with the -help flag or refer to the file itself.

Who is this library for?
========================

This library is written mainly for myself and those who appreciate how computers work in the real
world. It's meant to be the base layer of your application, having key data-structures that are
essential when working with low-level programming. In essence, the library provides a few features
that C failed to address - and unfortunately can't be fixed writing pure C. All of the internals of
the library are accessible to the user for this exact reason. As you can see, this document is a
simple txt file, which should reflect the simplicity and pragmatism of the code itself - nothing
fancy, and nothing shiny, just programming in its purest way.

Integrating with another project
================================

Integrating the Presheaf library to your project is trivial, as said above you have two main options:

a. Using the files src/presheaf.cpp and src/presheaf.hpp, embed the library directly into
   your codebase.
b. Compile the libary separately from your project, then link to it later.

Both of the above options apply directly to any of the modern build systems. If you know how your
tools work, it should be a piece of cake to integrate the library to your own project.

Library compile-time options
============================

The Presheaf library has many compile-time flags that you can use to tweak the behaviour of the,
implementation, and enable/disable features. You can find all of these flags documented in the
src/psh_core.hpp header file.

Documentation
=============

The code written in such a simple and understandable manner that the best source of information is
the code itself. I've also provided many comments in the headers documenting the behaviour of a given
function. Don't feel afraid to jump straight into code. This library is meant to be the stepping
stones of your codebase - if you don't understand how it works, then you won't understand your program
at all.

Dependencies
============

Explicitly, here we list all of the dependencies of the Presheaf library:

- libc:         stdio.h, stdint.h, stddef.h, stdarg.h, string.h, math.h, assert.h, limits.h
- Windows-only: Windows.h
- Unix-only:    unistd.h, errno.h, time.h, sys/mman.h