Refactor/better error codes (#18)

* Refactor status codes and remove deprecated header

- Introduced a new structure for status codes in status_codes.h, categorizing errors into Configuration, Connection, Io, Control, and Monitor.
- Removed the obsolete status_codes.hpp file, consolidating functionality into status_codes.h.
- Updated validation functions in validation.hpp to utilize the new status code structure for improved error handling.
- Adjusted documentation in serial_abort_read.h and serial_abort_write.h to reflect changes in status code usage.

* Refactor status code definitions in status_codes.h

- Changed ValueType from std::int32_t to std::int64_t for improved range.
- Replaced the make function with a GenCode template structure for generating error codes, enhancing clarity and maintainability.
- Updated error codes in Configuration, Connection, Io, Control, and Monitor categories to utilize the new GenCode structure.

* Enhance status code structure in status_codes.h

- Added an explicit conversion operator to the GenCode template for improved usability.
- Updated status code definitions in Configuration, Connection, Io, Control, and Monitor categories to utilize the GenCode structure directly, enhancing clarity and maintainability.

* Refactor status code organization in status_codes.h

- Moved status code definitions into a new cpp_core::status_codes namespace for better modularity.
- Introduced a detail namespace to encapsulate internal structures, enhancing code clarity.
- Updated references to ValueType and CategoryBase to reflect the new namespace structure, improving maintainability.

* Remove the Monitor struct from status_codes.h to streamline status code definitions and improve code clarity.

* Add status code definitions in a new header file

- Introduced a new header file status_code.h to define a structured approach for status codes within the cpp_core::status_codes namespace.
- Implemented a CategoryBase template for generating error codes, enhancing clarity and maintainability.
- Organized status codes into categories: Configuration, Connection, Io, and Control, each with specific error codes for improved usability.

* Refactor CategoryBase template in status_code.h

- Changed the CategoryBase template to accept a derived type instead of a category value, enhancing type safety and clarity.
- Updated the Configuration, Connection, Io, and Control structs to define their category codes directly, improving maintainability and readability of status code definitions.

* Update kCategoryMultiplier initialization in CategoryBase template

- Changed the initialization of kCategoryMultiplier from an assignment to a uniform initialization syntax, enhancing code consistency and clarity.

* Add new status code generation macros and enhance error handling

- Introduced CPP_CORE_STATUS_CATEGORY and CPP_CORE_CODE macros for streamlined status code definitions, improving maintainability and readability.
- Added isError and isSuccess functions for better error handling.
- Updated the CategoryBase template to support compile-time code generation, enhancing type safety and clarity in status code management.

* Refactor error handling functions in StatusCode

- Moved isError, isSuccess, and belongsTo functions into the StatusCode struct for better encapsulation and organization.
- Updated function signatures to use detail::ValueType for consistency with the new structure.
- Removed redundant definitions from the detail namespace, enhancing code clarity and maintainability.

* Enhance status code structure in status_code.h

- Refactored the Code template to accept a Category type, improving type safety and clarity.
- Introduced new member functions for retrieving the name and category of status codes.
- Replaced macro-based status code definitions with structured definitions for Configuration, Connection, and Io categories, enhancing maintainability and readability.

* Update include/cpp_core/status_code.h

Co-authored-by: Mqx <62719703+Mqxx@users.noreply.github.com>

* Enhance CategoryBase template in status_code.h

- Added static assertions to enforce constraints on category and local codes, improving safety against negative values and overflow.
- Introduced a new test category, FakeCategory, to validate the computation of status codes, ensuring correct behavior across edge cases and preventing overflow.
- Updated test cases to cover various scenarios, enhancing the robustness of the status code generation logic.

* test: move status code static asserts into compile test

---------

Co-authored-by: Mqx <62719703+Mqxx@users.noreply.github.com>

Author: Katze719

CMakeLists.txt

@@ -49,6 +49,13 @@ target_compile_features(cpp_core INTERFACE cxx_std_23)
 set(CMAKE_CXX_MODULE_STD 23)
 set(CMAKE_CXX_MODULE_EXTENSIONS OFF)
 
+include(CTest)
+
+if(BUILD_TESTING)
+    add_library(cpp_core_status_code_compile_test OBJECT tests/status_code_compile_test.cpp)
+    target_link_libraries(cpp_core_status_code_compile_test PRIVATE cpp_core::cpp_core)
+endif()
+
 # Install rules --------------------------------------------------------------
 include(GNUInstallDirs)
 

include/cpp_core.h

@@ -14,5 +14,5 @@
 
 #include "cpp_core/error_callback.h"
 #include "cpp_core/serial.h"
-#include "cpp_core/status_codes.h"
+#include "cpp_core/status_code.h"
 #include "cpp_core/version.hpp"

include/cpp_core/error_handling.hpp

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "status_codes.h"
+#include "status_code.h"
 
 #include <concepts>
 #include <string>

include/cpp_core/interface/serial_abort_read.h

@@ -12,11 +12,11 @@ extern "C"
      * @brief Abort a blocking read operation running in a different thread.
      *
      * The target read function returns immediately with
-     * ::cpp_core::StatusCodes::kAbortReadError.
+     * ::cpp_core::StatusCode::Io::kAbortReadError.
      *
      * @param handle Port handle.
      * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
-     * @return 0 on success or a negative error code from ::cpp_core::StatusCodes on error.
+     * @return 0 on success or a negative error code from ::cpp_core::StatusCode on error.
      */
     MODULE_API auto serialAbortRead(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
 

include/cpp_core/interface/serial_abort_write.h

@@ -12,11 +12,11 @@ extern "C"
      * @brief Abort a blocking write operation running in a different thread.
      *
      * The target write function returns immediately with
-     * ::cpp_core::StatusCodes::kAbortWriteError.
+     * ::cpp_core::StatusCode::Io::kAbortWriteError.
      *
      * @param handle Port handle.
      * @param error_callback [optional] Callback to invoke on error. Defined in error_callback.h. Default is `nullptr`.
-     * @return 0 on success or a negative error code from ::cpp_core::StatusCodes on error.
+     * @return 0 on success or a negative error code from ::cpp_core::StatusCode on error.
      */
     MODULE_API auto serialAbortWrite(int64_t handle, ErrorCallbackT error_callback = nullptr) -> int;
 

include/cpp_core/result.hpp

@@ -1,6 +1,6 @@
 #pragma once
 
-#include "status_codes.h"
+#include "status_code.h"
 
 #include <concepts>
 #include <expected>

include/cpp_core/status_code.h

@@ -0,0 +1,139 @@
+#pragma once
+
+#include <cstdint>
+#include <string_view>
+
+namespace cpp_core::status_codes
+{
+
+namespace detail
+{
+
+using ValueType = std::int64_t;
+
+inline constexpr ValueType kCategoryMultiplier{100};
+
+template <typename Category, ValueType NumericValue> struct Code
+{
+    static constexpr ValueType kValue = NumericValue;
+    std::string_view kName; // NOLINT(readability-identifier-naming)
+
+    // NOLINTNEXTLINE(google-explicit-constructor, hicpp-explicit-conversions)
+    constexpr operator ValueType() const noexcept
+    {
+        return kValue;
+    }
+    [[nodiscard]] constexpr auto value() const noexcept -> ValueType
+    {
+        return kValue;
+    }
+    [[nodiscard]] constexpr auto name() const noexcept -> std::string_view
+    {
+        return kName;
+    }
+    [[nodiscard]] constexpr auto category() const noexcept -> std::string_view
+    {
+        return Category::kCategoryName;
+    }
+};
+
+template <typename Derived> struct CategoryBase
+{
+  private:
+    constexpr CategoryBase() = default;
+
+  protected:
+    template <ValueType LocalCode> static consteval auto computeValue() -> ValueType
+    {
+        static_assert(Derived::kCategoryCode >= 0, "Category code must not be negative");
+        static_assert(LocalCode >= 0, "Code index must not be negative");
+        static_assert(LocalCode < kCategoryMultiplier, "Category overflow (max 99 codes)");
+        static_assert(Derived::kCategoryCode <=
+                          (std::numeric_limits<ValueType>::max() - kCategoryMultiplier + 1) / kCategoryMultiplier,
+                      "Category code too large, multiplication would overflow");
+        return -((Derived::kCategoryCode * kCategoryMultiplier) + LocalCode);
+    }
+
+    template <ValueType LocalCode> using Code = detail::Code<Derived, computeValue<LocalCode>()>;
+
+    friend Derived;
+};
+
+} // namespace detail
+
+struct StatusCode
+{
+    using ValueType = detail::ValueType;
+    static constexpr ValueType kSuccess = 0;
+
+    struct Configuration : detail::CategoryBase<Configuration>
+    {
+        static constexpr ValueType kCategoryCode = 1;
+        static constexpr std::string_view kCategoryName{"Configuration"};
+
+        static constexpr Code<0> kSetBaudrateError{"SetBaudrateError"};
+        static constexpr Code<1> kSetDataBitsError{"SetDataBitsError"};
+        static constexpr Code<2> kSetParityError{"SetParityError"};
+        static constexpr Code<3> kSetStopBitsError{"SetStopBitsError"};
+        static constexpr Code<4> kSetFlowControlError{"SetFlowControlError"};
+        static constexpr Code<5> kSetTimeoutError{"SetTimeoutError"};
+    };
+
+    struct Connection : detail::CategoryBase<Connection>
+    {
+        static constexpr ValueType kCategoryCode = 2;
+        static constexpr std::string_view kCategoryName{"Connection"};
+
+        static constexpr Code<0> kNotFoundError{"NotFoundError"};
+        static constexpr Code<1> kInvalidHandleError{"InvalidHandleError"};
+        static constexpr Code<2> kCloseHandleError{"CloseHandleError"};
+    };
+
+    struct Io : detail::CategoryBase<Io>
+    {
+        static constexpr ValueType kCategoryCode = 3;
+        static constexpr std::string_view kCategoryName{"Io"};
+
+        static constexpr Code<0> kReadError{"ReadError"};
+        static constexpr Code<1> kWriteError{"WriteError"};
+        static constexpr Code<2> kAbortReadError{"AbortReadError"};
+        static constexpr Code<3> kAbortWriteError{"AbortWriteError"};
+        static constexpr Code<4> kBufferError{"BufferError"};
+        static constexpr Code<5> kClearBufferInError{"ClearBufferInError"};
+        static constexpr Code<6> kClearBufferOutError{"ClearBufferOutError"};
+    };
+
+    struct Control : detail::CategoryBase<Control>
+    {
+        static constexpr ValueType kCategoryCode = 4;
+        static constexpr std::string_view kCategoryName{"Control"};
+
+        static constexpr Code<0> kSetDtrError{"SetDtrError"};
+        static constexpr Code<1> kSetRtsError{"SetRtsError"};
+        static constexpr Code<2> kGetModemStatusError{"GetModemStatusError"};
+        static constexpr Code<3> kSendBreakError{"SendBreakError"};
+        static constexpr Code<4> kGetStateError{"GetStateError"};
+        static constexpr Code<5> kSetStateError{"SetStateError"};
+    };
+
+    [[nodiscard]] static constexpr auto isError(ValueType code) noexcept -> bool
+    {
+        return code < 0;
+    }
+    [[nodiscard]] static constexpr auto isSuccess(ValueType code) noexcept -> bool
+    {
+        return code >= 0;
+    }
+    template <typename Category> [[nodiscard]] static constexpr auto belongsTo(ValueType code) noexcept -> bool
+    {
+        return code < 0 && (-code) / detail::kCategoryMultiplier == Category::kCategoryCode;
+    }
+};
+
+} // namespace cpp_core::status_codes
+
+namespace cpp_core
+{
+using StatusCodes = ::cpp_core::status_codes::detail::ValueType;
+using ::cpp_core::status_codes::StatusCode;
+} // namespace cpp_core