feat: initialize rix debug package

Author: GaspardKirira

.gitignore

@@ -1,41 +1,12 @@
-# Prerequisites
-*.d
+build*/
+.vix/
+.cache/
 
-# Compiled Object files
-*.slo
-*.lo
 *.o
 *.obj
-
-# Precompiled Headers
-*.gch
-*.pch
-
-# Linker files
-*.ilk
-
-# Debugger Files
-*.pdb
-
-# Compiled Dynamic libraries
-*.so
-*.dylib
-*.dll
-
-# Fortran module files
-*.mod
-*.smod
-
-# Compiled Static libraries
-*.lai
-*.la
 *.a
 *.lib
-
-# Executables
+*.so
+*.dll
+*.dylib
 *.exe
-*.out
-*.app
-
-# debug information files
-*.dwo

CMakeLists.txt

@@ -0,0 +1,32 @@
+cmake_minimum_required(VERSION 3.20)
+
+project(rix_debug
+  VERSION 0.1.0
+  DESCRIPTION "Debug printing, formatting, logging, and inspection utilities for Rix"
+  LANGUAGES CXX
+)
+
+option(RIX_DEBUG_BUILD_EXAMPLES "Build rix/debug examples" ON)
+option(RIX_DEBUG_BUILD_TESTS "Build rix/debug tests" ON)
+
+add_library(rix_debug INTERFACE)
+add_library(rix::debug ALIAS rix_debug)
+
+target_compile_features(rix_debug INTERFACE cxx_std_20)
+
+target_include_directories(rix_debug
+  INTERFACE
+    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+    $<INSTALL_INTERFACE:include>
+)
+
+if(CMAKE_CURRENT_SOURCE_DIR STREQUAL CMAKE_SOURCE_DIR)
+  if(RIX_DEBUG_BUILD_EXAMPLES)
+    add_subdirectory(examples)
+  endif()
+
+  if(RIX_DEBUG_BUILD_TESTS)
+    enable_testing()
+    add_subdirectory(tests)
+  endif()
+endif()

README.md

@@ -1,2 +1,3 @@
-# rix-thread
-Thread and synchronization utilities: thread creation, mutex, lock, and condition variables.
+# Debug
+
+Debug printing, formatting, logging, and inspection utilities for Rix.

examples/CMakeLists.txt

@@ -0,0 +1,8 @@
+add_executable(rix_debug_basic
+  basic.cpp
+)
+
+target_link_libraries(rix_debug_basic
+  PRIVATE
+    rix::debug
+)

examples/basic.cpp

@@ -0,0 +1,22 @@
+/**
+ * @file basic.cpp
+ * @brief Basic example for rix/debug.
+ */
+
+#include <rix/debug.hpp>
+
+int main()
+{
+  rixlib::debug::Debug debug;
+
+  debug.print("Hello {}", "Rix");
+
+  auto text = debug.format("Package: {}", "rix/debug");
+
+  debug.log("loaded {} rows", 3);
+  debug.log.warn("slow request: {}ms", 120);
+
+  debug.inspect(text);
+
+  return 0;
+}

include/rix/debug.hpp

@@ -0,0 +1,26 @@
+/**
+ * @file debug.hpp
+ * @brief Unified debug module for Rix.
+ */
+
+#ifndef RIXCPP_DEBUG_INCLUDE_RIX_DEBUG_HPP_INCLUDED
+#define RIXCPP_DEBUG_INCLUDE_RIX_DEBUG_HPP_INCLUDED
+
+#include <rix/debug/format.hpp>
+#include <rix/debug/inspect.hpp>
+#include <rix/debug/log.hpp>
+#include <rix/debug/print.hpp>
+
+namespace rixlib::debug
+{
+  class Debug
+  {
+  public:
+    Format format{};
+    Print print{};
+    Log log{};
+    Inspect inspect{};
+  };
+}
+
+#endif // RIXCPP_DEBUG_INCLUDE_RIX_DEBUG_HPP_INCLUDED

include/rix/debug/format.hpp

@@ -0,0 +1,230 @@
+/**
+ * @file format.hpp
+ * @brief Placeholder-based formatting API for rix/debug.
+ */
+
+#ifndef RIXCPP_DEBUG_INCLUDE_RIX_DEBUG_FORMAT_HPP_INCLUDED
+#define RIXCPP_DEBUG_INCLUDE_RIX_DEBUG_FORMAT_HPP_INCLUDED
+
+#include <array>
+#include <cstddef>
+#include <sstream>
+#include <stdexcept>
+#include <string>
+#include <string_view>
+#include <type_traits>
+
+namespace rixlib::debug
+{
+  class FormatError : public std::runtime_error
+  {
+  public:
+    explicit FormatError(const std::string &message)
+        : std::runtime_error(message)
+    {
+    }
+
+    explicit FormatError(const char *message)
+        : std::runtime_error(message)
+    {
+    }
+  };
+
+  namespace detail
+  {
+    template <typename T>
+    [[nodiscard]] std::string render_value(const T &value)
+    {
+      std::ostringstream stream;
+
+      if constexpr (std::is_same_v<std::remove_cvref_t<T>, bool>)
+      {
+        stream << (value ? "true" : "false");
+      }
+      else
+      {
+        stream << value;
+      }
+
+      return stream.str();
+    }
+
+    class RenderedArgs
+    {
+    public:
+      template <std::size_t N>
+      explicit RenderedArgs(const std::array<std::string, N> &values) noexcept
+          : data_(values.data()), size_(N)
+      {
+      }
+
+      [[nodiscard]] std::size_t size() const noexcept
+      {
+        return size_;
+      }
+
+      [[nodiscard]] const std::string &at(std::size_t index) const
+      {
+        if (index >= size_)
+        {
+          throw FormatError("format argument index out of range");
+        }
+
+        return data_[index];
+      }
+
+    private:
+      const std::string *data_{nullptr};
+      std::size_t size_{0};
+    };
+
+    [[nodiscard]] inline std::size_t parse_index(std::string_view text)
+    {
+      if (text.empty())
+      {
+        throw FormatError("empty explicit format index");
+      }
+
+      std::size_t value = 0;
+
+      for (char ch : text)
+      {
+        if (ch < '0' || ch > '9')
+        {
+          throw FormatError("invalid explicit format index");
+        }
+
+        value = (value * 10u) + static_cast<std::size_t>(ch - '0');
+      }
+
+      return value;
+    }
+
+    inline void render_format_string(
+        std::string &out,
+        std::string_view fmt,
+        const RenderedArgs &args)
+    {
+      std::size_t i = 0;
+      std::size_t next_auto_index = 0;
+      bool used_auto_index = false;
+      bool used_explicit_index = false;
+
+      while (i < fmt.size())
+      {
+        const char ch = fmt[i];
+
+        if (ch == '{')
+        {
+          if ((i + 1u) < fmt.size() && fmt[i + 1u] == '{')
+          {
+            out.push_back('{');
+            i += 2u;
+            continue;
+          }
+
+          const std::size_t close = fmt.find('}', i + 1u);
+
+          if (close == std::string_view::npos)
+          {
+            throw FormatError("unmatched '{' in format string");
+          }
+
+          const std::string_view token = fmt.substr(i + 1u, close - (i + 1u));
+
+          if (token.empty())
+          {
+            if (used_explicit_index)
+            {
+              throw FormatError("cannot mix automatic and explicit format indexes");
+            }
+
+            used_auto_index = true;
+            out += args.at(next_auto_index++);
+          }
+          else
+          {
+            if (used_auto_index)
+            {
+              throw FormatError("cannot mix automatic and explicit format indexes");
+            }
+
+            if (token.find(':') != std::string_view::npos)
+            {
+              throw FormatError("format specifiers are not supported yet");
+            }
+
+            used_explicit_index = true;
+            out += args.at(parse_index(token));
+          }
+
+          i = close + 1u;
+          continue;
+        }
+
+        if (ch == '}')
+        {
+          if ((i + 1u) < fmt.size() && fmt[i + 1u] == '}')
+          {
+            out.push_back('}');
+            i += 2u;
+            continue;
+          }
+
+          throw FormatError("single '}' encountered in format string");
+        }
+
+        out.push_back(ch);
+        ++i;
+      }
+    }
+
+    [[nodiscard]] inline std::size_t estimate_output_size(
+        std::string_view fmt,
+        const RenderedArgs &args)
+    {
+      std::size_t total = fmt.size();
+
+      for (std::size_t i = 0; i < args.size(); ++i)
+      {
+        total += args.at(i).size();
+      }
+
+      return total;
+    }
+  }
+
+  class Format
+  {
+  public:
+    template <typename... Args>
+    [[nodiscard]] std::string operator()(std::string_view fmt, const Args &...args) const
+    {
+      std::array<std::string, sizeof...(Args)> rendered_args{
+          detail::render_value(args)...};
+
+      const detail::RenderedArgs rendered{rendered_args};
+
+      std::string output;
+      output.reserve(detail::estimate_output_size(fmt, rendered));
+      detail::render_format_string(output, fmt, rendered);
+
+      return output;
+    }
+
+    template <typename... Args>
+    void append(std::string &out, std::string_view fmt, const Args &...args) const
+    {
+      out += operator()(fmt, args...);
+    }
+
+    template <typename... Args>
+    void to(std::string &out, std::string_view fmt, const Args &...args) const
+    {
+      out.clear();
+      append(out, fmt, args...);
+    }
+  };
+}
+
+#endif // RIXCPP_DEBUG_INCLUDE_RIX_DEBUG_FORMAT_HPP_INCLUDED