wireforge 0.1.0__py3-none-any.whl

wireforge/__init__.py

@@ -0,0 +1,3 @@
+"""WireForge: schema-driven wire-format toolkit."""
+
+__version__ = "0.1.0"

wireforge/_data/cmake/WireForgeConfig.cmake

@@ -0,0 +1,29 @@
+# CMake package of WireForge: find_package(WireForge) gives
+#  - wireforge::runtime: the header-only C++17 runtime;
+#  - wireforge_generate(): generates C++ code from a WireForge project at configure time.
+# Works from an installed tree (<prefix>/lib/cmake/WireForge) and from the Python package
+# (`wireforge cmake-dir` prints this directory).
+include_guard(GLOBAL)
+
+set(WIREFORGE_INCLUDE_DIR "")
+foreach(candidate "${CMAKE_CURRENT_LIST_DIR}/../runtime/include" "${CMAKE_CURRENT_LIST_DIR}/../../../include"
+        "${CMAKE_CURRENT_LIST_DIR}/../../runtime/include")
+  if(NOT WIREFORGE_INCLUDE_DIR AND EXISTS "${candidate}/wireforge/status.hpp")
+    get_filename_component(WIREFORGE_INCLUDE_DIR "${candidate}" ABSOLUTE)
+  endif()
+endforeach()
+if(NOT WIREFORGE_INCLUDE_DIR)
+  set(WireForge_FOUND FALSE)
+  set(WireForge_NOT_FOUND_MESSAGE "the WireForge runtime headers were not found next to ${CMAKE_CURRENT_LIST_DIR}")
+  return()
+endif()
+
+if(NOT TARGET wireforge::runtime)
+  add_library(wireforge::runtime INTERFACE IMPORTED)
+  set_target_properties(wireforge::runtime PROPERTIES
+    INTERFACE_INCLUDE_DIRECTORIES "${WIREFORGE_INCLUDE_DIR}"
+    INTERFACE_COMPILE_FEATURES cxx_std_17)
+endif()
+
+include("${CMAKE_CURRENT_LIST_DIR}/WireForgeGenerate.cmake")
+set(WireForge_FOUND TRUE)

wireforge/_data/cmake/WireForgeConfigVersion.cmake

@@ -0,0 +1,15 @@
+# Version of the WireForge CMake package; compatible within the same major version.
+set(PACKAGE_VERSION "0.1.0")
+if(PACKAGE_FIND_VERSION VERSION_GREATER PACKAGE_VERSION)
+  set(PACKAGE_VERSION_COMPATIBLE FALSE)
+else()
+  string(REGEX MATCH "^[0-9]+" _wireforge_major "${PACKAGE_VERSION}")
+  if(PACKAGE_FIND_VERSION_MAJOR STREQUAL "" OR PACKAGE_FIND_VERSION_MAJOR STREQUAL _wireforge_major)
+    set(PACKAGE_VERSION_COMPATIBLE TRUE)
+  else()
+    set(PACKAGE_VERSION_COMPATIBLE FALSE)
+  endif()
+  if(PACKAGE_FIND_VERSION STREQUAL PACKAGE_VERSION)
+    set(PACKAGE_VERSION_EXACT TRUE)
+  endif()
+endif()

wireforge/_data/cmake/WireForgeGenerate.cmake

@@ -0,0 +1,64 @@
+# wireforge_generate(<target> PROJECT <dir> [OUTPUT <dir>] [PLUGINS <file>] [TESTS])
+#
+# Runs `wireforge generate` at configure time (again whenever a model file changes) and creates
+# the INTERFACE library <target> with the generated headers, the project's user include
+# directories and wireforge::runtime. With TESTS the GoogleTest project is generated too
+# (<OUTPUT>/<project>/generated_tests). The generator is the `wireforge` command, or
+# `python -m wireforge.cli` when only the Python package is found (WIREFORGE_COMMAND overrides).
+include_guard(GLOBAL)
+
+function(_wireforge_command result)
+  if(WIREFORGE_COMMAND)
+    set(${result} ${WIREFORGE_COMMAND} PARENT_SCOPE)
+    return()
+  endif()
+  find_program(WIREFORGE_EXECUTABLE wireforge)
+  if(WIREFORGE_EXECUTABLE)
+    set(${result} "${WIREFORGE_EXECUTABLE}" PARENT_SCOPE)
+    return()
+  endif()
+  find_package(Python3 REQUIRED COMPONENTS Interpreter)
+  set(${result} "${Python3_EXECUTABLE}" -m wireforge.cli PARENT_SCOPE)
+endfunction()
+
+function(wireforge_generate target)
+  cmake_parse_arguments(PARSE_ARGV 1 arg "TESTS" "PROJECT;OUTPUT;PLUGINS" "")
+  if(NOT arg_PROJECT)
+    message(FATAL_ERROR "wireforge_generate(${target}): PROJECT is required")
+  endif()
+  get_filename_component(project "${arg_PROJECT}" ABSOLUTE)
+  set(output "${CMAKE_CURRENT_BINARY_DIR}/wireforge_${target}")
+  if(arg_OUTPUT)
+    get_filename_component(output "${arg_OUTPUT}" ABSOLUTE)
+  endif()
+  _wireforge_command(command)
+  set(arguments generate "${project}" -o "${output}")
+  if(arg_TESTS)
+    list(APPEND arguments --tests)
+  endif()
+  if(arg_PLUGINS)
+    list(APPEND arguments --plugins "${arg_PLUGINS}")
+  endif()
+  execute_process(COMMAND ${command} ${arguments} RESULT_VARIABLE failed OUTPUT_VARIABLE log ERROR_VARIABLE log)
+  if(failed)
+    message(FATAL_ERROR "wireforge_generate(${target}) failed:\n${log}")
+  endif()
+  file(GLOB_RECURSE model_files CONFIGURE_DEPENDS "${project}/*.yaml")
+  set_property(DIRECTORY APPEND PROPERTY CMAKE_CONFIGURE_DEPENDS ${model_files})
+  execute_process(COMMAND ${command} get "${project}" /user_includes/include_dirs --json
+                  RESULT_VARIABLE missing OUTPUT_VARIABLE answer ERROR_QUIET)
+  set(include_dirs "")
+  if(NOT missing)
+    string(JSON count LENGTH "${answer}" data value)
+    if(count GREATER 0)
+      math(EXPR last "${count} - 1")
+      foreach(index RANGE ${last})
+        string(JSON directory GET "${answer}" data value ${index})
+        list(APPEND include_dirs "${project}/${directory}")
+      endforeach()
+    endif()
+  endif()
+  add_library(${target} INTERFACE)
+  target_include_directories(${target} INTERFACE "${output}" ${include_dirs})
+  target_link_libraries(${target} INTERFACE wireforge::runtime)
+endfunction()

wireforge/_data/runtime/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oguzhan KAYNAK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

wireforge/_data/runtime/include/wireforge/array_access.hpp

@@ -0,0 +1,35 @@
+/**
+ * @file array_access.hpp
+ * @brief Element access of std::array without the exception path of std::array::at().
+ */
+#ifndef WIREFORGE_ARRAY_ACCESS_HPP
+#define WIREFORGE_ARRAY_ACCESS_HPP
+
+#include <array>
+#include <cstddef>
+#include <iterator>
+
+namespace wireforge {
+
+/**
+ * @brief Element @p index of @p array.
+ *
+ * The caller guarantees `index < N` (the runtime only uses indices that are bounded by
+ * construction). Unlike std::array::at() this references no exception-throwing library code, so
+ * builds without exceptions and without heap stay free of them.
+ */
+template <typename T, std::size_t N>
+[[nodiscard]] constexpr T& array_at(std::array<T, N>& array, std::size_t index) noexcept {
+    return *std::next(array.begin(), static_cast<std::ptrdiff_t>(index));
+}
+
+/// @brief Element @p index of a const @p array (see the non-const overload).
+template <typename T, std::size_t N>
+[[nodiscard]] constexpr const T& array_at(const std::array<T, N>& array,
+                                          std::size_t index) noexcept {
+    return *std::next(array.begin(), static_cast<std::ptrdiff_t>(index));
+}
+
+} // namespace wireforge
+
+#endif // WIREFORGE_ARRAY_ACCESS_HPP

wireforge/_data/runtime/include/wireforge/bit_utils.hpp

@@ -0,0 +1,226 @@
+/**
+ * @file bit_utils.hpp
+ * @brief Bit masks, two's complement helpers and packing of bit-field groups.
+ */
+#ifndef WIREFORGE_BIT_UTILS_HPP
+#define WIREFORGE_BIT_UTILS_HPP
+
+#include "wireforge/status.hpp"
+
+#include <cstdint>
+#include <type_traits>
+
+namespace wireforge {
+
+/**
+ * @brief Converts @p value to the integer type @p To; the value must fit.
+ *
+ * For conversions whose source width depends on the platform (std::size_t is 32 bits wide on
+ * 32-bit targets), so that the same code is free of useless-cast and conversion warnings on
+ * every target.
+ */
+template <typename To, typename From> [[nodiscard]] constexpr To narrow_to(From value) noexcept {
+    static_assert(std::is_integral_v<To> && std::is_integral_v<From>, "integer conversions only");
+    return static_cast<To>(value);
+}
+
+/// @brief Order in which the fields of a bit group are placed in the group.
+enum class BitOrder : std::uint8_t {
+    MsbFirst, ///< The first field takes the most significant bits of the group.
+    LsbFirst, ///< The first field takes the least significant bits of the group.
+};
+
+/// @brief Largest supported bit width (fields and bit groups).
+inline constexpr unsigned kMaxBits = 64U;
+
+/**
+ * @brief Mask with the low @p bits bits set.
+ * @param bits Number of bits, 0..64.
+ */
+[[nodiscard]] constexpr std::uint64_t low_mask(unsigned bits) noexcept {
+    return bits >= kMaxBits ? ~std::uint64_t{0U} : ((std::uint64_t{1U} << bits) - 1U);
+}
+
+/// @brief true when @p value is representable as an unsigned integer of @p bits bits.
+[[nodiscard]] constexpr bool fits_unsigned(std::uint64_t value, unsigned bits) noexcept {
+    return (value & ~low_mask(bits)) == 0U;
+}
+
+/**
+ * @brief true when @p value is representable as a two's complement integer of @p bits bits.
+ * @param value Value to test.
+ * @param bits Width, 1..64 (0 always gives false).
+ */
+[[nodiscard]] constexpr bool fits_signed(std::int64_t value, unsigned bits) noexcept {
+    if (bits == 0U) {
+        return false;
+    }
+    if (bits >= kMaxBits) {
+        return true;
+    }
+    const std::int64_t limit = std::int64_t{1} << (bits - 1U);
+    return value >= -limit && value < limit;
+}
+
+/// @brief Two's complement bit pattern of @p value truncated to @p bits bits.
+[[nodiscard]] constexpr std::uint64_t to_twos_complement(std::int64_t value,
+                                                         unsigned bits) noexcept {
+    return static_cast<std::uint64_t>(value) & low_mask(bits);
+}
+
+/**
+ * @brief Interprets the low @p bits bits of @p raw as two's complement and sign-extends them.
+ *
+ * Avoids the implementation-defined unsigned-to-signed conversion of C++17.
+ * @param raw Bit pattern; bits above @p bits are ignored.
+ * @param bits Width, 1..64.
+ */
+[[nodiscard]] constexpr std::int64_t sign_extend(std::uint64_t raw, unsigned bits) noexcept {
+    const std::uint64_t mask = low_mask(bits);
+    const std::uint64_t value = raw & mask;
+    const std::uint64_t sign_bit = std::uint64_t{1U} << (bits - 1U);
+    if ((value & sign_bit) == 0U) {
+        return static_cast<std::int64_t>(value);
+    }
+    return -static_cast<std::int64_t>(~value & mask) - 1;
+}
+
+/// @brief Reverses the order of the low @p bits bits of @p value.
+[[nodiscard]] constexpr std::uint64_t reflect(std::uint64_t value, unsigned bits) noexcept {
+    std::uint64_t result = 0U;
+    for (unsigned index = 0U; index < bits; ++index) {
+        result = (result << 1U) | ((value >> index) & 1U);
+    }
+    return result;
+}
+
+/**
+ * @brief Packs consecutive bit fields into one container integer.
+ *
+ * The group is 8..64 bits wide, a multiple of 8. Fields are added in declaration order with put();
+ * when complete(), the container is written with ByteWriter::write_bits in the message byte order.
+ */
+class BitPacker {
+public:
+    /**
+     * @param total_bits Width of the group: 8, 16, ..., 64.
+     * @param order Placement of the first field.
+     */
+    constexpr BitPacker(unsigned total_bits, BitOrder order) noexcept
+        : total_bits_(total_bits), order_(order) {}
+
+    /**
+     * @brief Appends the next unsigned field.
+     * @param value Field value.
+     * @param bits Field width.
+     * @return Status::OutOfRange when @p value needs more than @p bits bits; Status::InvalidState
+     *         when the group width is invalid, @p bits is 0 or the field does not fit the group.
+     */
+    constexpr Status put(std::uint64_t value, unsigned bits) noexcept {
+        if (!valid() || bits == 0U || bits > total_bits_ - used_bits_) {
+            return Status::InvalidState;
+        }
+        if (!fits_unsigned(value, bits)) {
+            return Status::OutOfRange;
+        }
+        const unsigned shift =
+            order_ == BitOrder::MsbFirst ? total_bits_ - used_bits_ - bits : used_bits_;
+        container_ |= value << shift;
+        used_bits_ += bits;
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Appends the next signed field as @p bits-bit two's complement.
+     * @return As put(); Status::OutOfRange when @p value does not fit @p bits bits.
+     */
+    constexpr Status put_signed(std::int64_t value, unsigned bits) noexcept {
+        if (!fits_signed(value, bits)) {
+            return bits == 0U ? Status::InvalidState : Status::OutOfRange;
+        }
+        return put(to_twos_complement(value, bits), bits);
+    }
+
+    /// @brief true when the group width is 8..64 and a multiple of 8.
+    [[nodiscard]] constexpr bool valid() const noexcept {
+        return total_bits_ >= 8U && total_bits_ <= kMaxBits && total_bits_ % 8U == 0U;
+    }
+    /// @brief true when the fields fill the whole group.
+    [[nodiscard]] constexpr bool complete() const noexcept {
+        return valid() && used_bits_ == total_bits_;
+    }
+    /// @brief Width of the group in bits.
+    [[nodiscard]] constexpr unsigned total_bits() const noexcept { return total_bits_; }
+    /// @brief Packed value of the group.
+    [[nodiscard]] constexpr std::uint64_t container() const noexcept { return container_; }
+
+private:
+    unsigned total_bits_;
+    unsigned used_bits_ = 0U;
+    BitOrder order_;
+    std::uint64_t container_ = 0U;
+};
+
+/// @brief Splits the container integer of a bit group back into fields, in declaration order.
+class BitUnpacker {
+public:
+    /**
+     * @param container Packed group value, usually from ByteReader::read_bits.
+     * @param total_bits Width of the group: 8, 16, ..., 64.
+     * @param order Placement of the first field.
+     */
+    constexpr BitUnpacker(std::uint64_t container, unsigned total_bits, BitOrder order) noexcept
+        : container_(container), total_bits_(total_bits), order_(order) {}
+
+    /**
+     * @brief Extracts the next unsigned field.
+     * @param[out] value Field value; unchanged on failure.
+     * @param bits Field width.
+     * @return Status::InvalidState when the group is invalid, @p bits is 0 or the group is
+     *         exhausted.
+     */
+    constexpr Status get(std::uint64_t& value, unsigned bits) noexcept {
+        if (!valid() || bits == 0U || bits > total_bits_ - used_bits_) {
+            return Status::InvalidState;
+        }
+        const unsigned shift =
+            order_ == BitOrder::MsbFirst ? total_bits_ - used_bits_ - bits : used_bits_;
+        value = (container_ >> shift) & low_mask(bits);
+        used_bits_ += bits;
+        return Status::Ok;
+    }
+
+    /**
+     * @brief Extracts the next field as @p bits-bit two's complement, sign-extended.
+     * @param[out] value Field value; unchanged on failure.
+     * @param bits Field width.
+     * @return As get().
+     */
+    constexpr Status get_signed(std::int64_t& value, unsigned bits) noexcept {
+        std::uint64_t raw = 0U;
+        const Status status = get(raw, bits);
+        if (status == Status::Ok) {
+            value = sign_extend(raw, bits);
+        }
+        return status;
+    }
+
+    /// @brief true when the group width is 8..64 and a multiple of 8.
+    [[nodiscard]] constexpr bool valid() const noexcept {
+        return total_bits_ >= 8U && total_bits_ <= kMaxBits && total_bits_ % 8U == 0U;
+    }
+    /// @brief true when every bit of the group has been extracted.
+    [[nodiscard]] constexpr bool complete() const noexcept {
+        return valid() && used_bits_ == total_bits_;
+    }
+
+private:
+    std::uint64_t container_;
+    unsigned total_bits_;
+    unsigned used_bits_ = 0U;
+    BitOrder order_;
+};
+
+} // namespace wireforge
+
+#endif // WIREFORGE_BIT_UTILS_HPP