@micro-os-plus/micro-test-plus 3.3.1 → 4.1.0

package/include/micro-os-plus/micro-test-plus/expression-formatter.h

@@ -0,0 +1,669 @@
+/*
+ * This file is part of the µOS++ project (https://micro-os-plus.github.io/).
+ * Copyright (c) 2021-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can be
+ * obtained from https://opensource.org/licenses/mit.
+ *
+ * Major parts of the code are inspired from v1.1.8 of the Boost UT project,
+ * released under the terms of the Boost Version 1.0 Software License,
+ * which can be obtained from https://www.boost.org/LICENSE_1_0.txt.
+ */
+
+// ----------------------------------------------------------------------------
+
+/**
+ * @file
+ * @brief C++ header file with declarations for the µTest++ expression
+ * formatter.
+ *
+ * @details
+ * This header provides the `expression_formatter` class, which encapsulates
+ * all value-formatting logic used by the µTest++ framework. The class owns
+ * a `std::string` buffer and exposes `operator<<` overloads for every
+ * standard arithmetic type, character type, string, pointer, container,
+ * and framework expression type derived from `detail::op`.
+ *
+ * By consolidating the formatting operators and their shared `append_number_`
+ * helper into a single class, the `reporter` is relieved of those
+ * responsibilities, and `detail::deferred_reporter` can pre-format expression
+ * text at construction time without requiring `reporter` or `subtest` to be
+ * complete at that point.
+ *
+ * Colour-code processing is intentionally excluded from this class; it
+ * remains the responsibility of the owning `reporter`.
+ *
+ * All definitions reside within the `micro_os_plus::micro_test_plus`
+ * namespace, ensuring clear separation from user code and minimising the
+ * risk of naming conflicts.
+ *
+ * This file is intended solely for internal use within the framework and
+ * should not be included directly by user code.
+ */
+
+#ifndef MICRO_TEST_PLUS_EXPRESSION_FORMATTER_H_
+#define MICRO_TEST_PLUS_EXPRESSION_FORMATTER_H_
+
+// ----------------------------------------------------------------------------
+
+#ifdef __cplusplus
+
+// ----------------------------------------------------------------------------
+
+#include <charconv>
+#include <cstdio>
+#include <string>
+#include <string_view>
+
+#include "type-traits.h"
+#include "detail.h"
+
+// ----------------------------------------------------------------------------
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic push
+#pragma GCC diagnostic ignored "-Wpadded"
+#pragma GCC diagnostic ignored "-Waggregate-return"
+#if defined(__clang__)
+#pragma clang diagnostic ignored "-Wc++98-compat"
+#pragma clang diagnostic ignored "-Wc++98-compat-pedantic"
+#endif
+#endif
+
+// ============================================================================
+
+namespace micro_os_plus::micro_test_plus
+{
+  // --------------------------------------------------------------------------
+
+  namespace detail
+  {
+    // ------------------------------------------------------------------------
+
+    /**
+     * @struct colours
+     * @brief Colours used to highlight pass and fail results in test reports.
+     *
+     * @details
+     * The `colours` structure defines ANSI escape sequences for terminal
+     * output, enabling colour-coded highlighting of test outcomes. The `pass`
+     * member specifies the colour for successful results (typically green),
+     * while the `fail` member specifies the colour for failed results
+     * (typically red). The `none` member resets the colour to the terminal
+     * default.
+     *
+     * These colour codes enhance the clarity and professionalism of test
+     * reports by making it immediately apparent which tests have passed or
+     * failed, thereby improving the overall user experience when reviewing
+     * test results.
+     *
+     * @var colours::none
+     * ANSI escape sequence to reset the terminal colour to default.
+     * @var colours::pass
+     * ANSI escape sequence to set the terminal colour for passing results
+     * (green).
+     * @var colours::fail
+     * ANSI escape sequence to set the terminal colour for failing results
+     * (red).
+     *
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
+    struct colours
+    {
+      const char* none = ""; /**< @brief Terminal colour reset sequence. */
+      const char* pass
+          = ""; /**< @brief Terminal colour sequence for passing tests. */
+      const char* fail
+          = ""; /**< @brief Terminal colour sequence for failing tests. */
+    };
+
+    inline constexpr colours colours_red_green = {
+      "\033[0m", /**< @brief Terminal colour reset sequence. */
+      "\033[32m", /**< @brief Green colour sequence for passing tests. */
+      "\033[31m" /**< @brief Red colour sequence for failing tests. */
+    };
+
+    // ========================================================================
+
+    /**
+     * @brief Formats values and expressions into an owned string buffer.
+     *
+     * @details
+     * `expression_formatter` owns a `std::string` buffer and provides
+     * `operator<<` overloads for all standard arithmetic types, character
+     * types, strings, pointers, containers, and framework expression types
+     * derived from `detail::op`.
+     *
+     * The numeric overloads append a type suffix (e.g., `42u`, `3l`, `1.0f`)
+     * matching the conventions used in the existing reporter output, so that
+     * the formatted text is identical whether produced by the reporter
+     * directly or pre-formatted by a deferred reporter.
+     *
+     * The class is non-copyable and non-movable to avoid accidental copying
+     * of the internal buffer.
+     *
+     * @headerfile micro-test-plus.h <micro-os-plus/micro-test-plus.h>
+     */
+    class expression_formatter
+    {
+    public:
+      /**
+       * @brief Constructor with colour configuration.
+       *
+       * @param colours Reference to a `colours` instance for output
+       * formatting.
+       */
+      expression_formatter (colours& colours) noexcept;
+
+      /**
+       * @brief Deleted copy constructor to prevent copying.
+       */
+      expression_formatter (const expression_formatter&) = delete;
+
+      /**
+       * @brief Deleted move constructor to prevent moving.
+       */
+      expression_formatter (expression_formatter&&) = delete;
+
+      /**
+       * @brief Deleted copy assignment operator to prevent copying.
+       */
+      expression_formatter&
+      operator= (const expression_formatter&)
+          = delete;
+
+      /**
+       * @brief Deleted move assignment operator to prevent moving.
+       */
+      expression_formatter&
+      operator= (expression_formatter&&)
+          = delete;
+
+      /**
+       * @brief Default destructor.
+       */
+      ~expression_formatter () = default;
+
+      // ----------------------------------------------------------------------
+      // Primitive operator<< overloads.
+
+      /**
+       * @brief Appends a string view to the buffer.
+       *
+       * @param sv The string view to append.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (std::string_view sv);
+
+      /**
+       * @brief Appends a single character to the buffer.
+       *
+       * @param c The character to append.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (char c);
+
+      /**
+       * @brief Appends a null-terminated C string to the buffer.
+       *
+       * @param s The C string to append.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (const char* s);
+
+      /**
+       * @brief Appends the string representation of a boolean value.
+       *
+       * @param v The boolean value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (bool v);
+
+      /**
+       * @brief Appends the string `"nullptr"`.
+       *
+       * @return Reference to this instance.
+       */
+      expression_formatter& operator<< (std::nullptr_t);
+
+      /**
+       * @brief Appends a signed char value with type suffix `"c"`.
+       *
+       * @param c The signed char value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (signed char c);
+
+      /**
+       * @brief Appends an unsigned char value with type suffix `"uc"`.
+       *
+       * @param c The unsigned char value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (unsigned char c);
+
+      /**
+       * @brief Appends a signed short value with type suffix `"s"`.
+       *
+       * @param v The signed short value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (signed short v);
+
+      /**
+       * @brief Appends an unsigned short value with type suffix `"us"`.
+       *
+       * @param v The unsigned short value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (unsigned short v);
+
+      /**
+       * @brief Appends a signed int value (no suffix).
+       *
+       * @param v The signed int value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (signed int v);
+
+      /**
+       * @brief Appends an unsigned int value with type suffix `"u"`.
+       *
+       * @param v The unsigned int value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (unsigned int v);
+
+      /**
+       * @brief Appends a signed long value with type suffix `"l"`.
+       *
+       * @param v The signed long value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (signed long v);
+
+      /**
+       * @brief Appends an unsigned long value with type suffix `"ul"`.
+       *
+       * @param v The unsigned long value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (unsigned long v);
+
+      /**
+       * @brief Appends a signed long long value with type suffix `"ll"`.
+       *
+       * @param v The signed long long value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (signed long long v);
+
+      /**
+       * @brief Appends an unsigned long long value with type suffix `"ull"`.
+       *
+       * @param v The unsigned long long value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (unsigned long long v);
+
+      /**
+       * @brief Appends a float value with type suffix `"f"`.
+       *
+       * @param v The float value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (float v);
+
+      /**
+       * @brief Appends a double value (no suffix).
+       *
+       * @param v The double value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (double v);
+
+      /**
+       * @brief Appends a long double value with type suffix `"l"`.
+       *
+       * @param v The long double value.
+       * @return Reference to this instance.
+       */
+      expression_formatter&
+      operator<< (long double v);
+
+      // ----------------------------------------------------------------------
+      // Template operator<< overloads.
+
+      /**
+       * @brief Appends the hexadecimal address of a pointer.
+       *
+       * @details
+       * Null pointers are rendered as `"0x0"`. Non-null pointers are
+       * formatted with `snprintf` using the `%p` specifier.
+       *
+       * @tparam T The type pointed to.
+       * @param v The pointer value.
+       * @return Reference to this instance.
+       */
+      template <typename T>
+      expression_formatter&
+      operator<< (T* v);
+
+      /**
+       * @brief Appends the value of an op expression via `detail::get`.
+       *
+       * @tparam T An expression type satisfying `type_traits::is_op<T>`.
+       * @param t The expression object.
+       * @return Reference to this instance.
+       */
+      template <class T>
+        requires type_traits::is_op<T>
+      expression_formatter&
+      operator<< (const T& t);
+
+      /**
+       * @brief Appends a genuine integral value without a type suffix.
+       *
+       * @tparam T The underlying integral type.
+       * @param v The strongly-typed integral value.
+       * @return Reference to this instance.
+       */
+      template <class T>
+      expression_formatter&
+      operator<< (const type_traits::genuine_integral_value<T>& v);
+
+      /**
+       * @brief Appends a container's elements enclosed in braces.
+       *
+       * @details
+       * Elements are formatted as `{ e1, e2, … }` by iterating the
+       * container and recursing through `operator<<` for each element.
+       *
+       * @tparam T A container type satisfying `type_traits::container_like`
+       * that does not have `npos`.
+       * @param t The container.
+       * @return Reference to this instance.
+       */
+      template <class T>
+        requires (type_traits::container_like<T>
+                  and not type_traits::has_npos<T>)
+      expression_formatter&
+      operator<< (const T& t);
+
+      // ----------------------------------------------------------------------
+      // Compound expression operator<< overloads (without colour).
+
+      /**
+       * @brief Formats an equality comparison as `lhs == rhs`.
+       *
+       * @tparam Lhs_T Left-hand operand type.
+       * @tparam Rhs_T Right-hand operand type.
+       * @param op The equality expression.
+       * @return Reference to this instance.
+       */
+      template <class Lhs_T, class Rhs_T>
+      expression_formatter&
+      operator<< (const detail::eq_<Lhs_T, Rhs_T>& op);
+
+      /**
+       * @brief Formats an inequality comparison as `lhs != rhs`.
+       *
+       * @tparam Lhs_T Left-hand operand type.
+       * @tparam Rhs_T Right-hand operand type.
+       * @param op The inequality expression.
+       * @return Reference to this instance.
+       */
+      template <class Lhs_T, class Rhs_T>
+      expression_formatter&
+      operator<< (const detail::ne_<Lhs_T, Rhs_T>& op);
+
+      /**
+       * @brief Formats a greater-than comparison as `lhs > rhs`.
+       *
+       * @tparam Lhs_T Left-hand operand type.
+       * @tparam Rhs_T Right-hand operand type.
+       * @param op The greater-than expression.
+       * @return Reference to this instance.
+       */
+      template <class Lhs_T, class Rhs_T>
+      expression_formatter&
+      operator<< (const detail::gt_<Lhs_T, Rhs_T>& op);
+
+      /**
+       * @brief Formats a greater-than-or-equal comparison as `lhs >= rhs`.
+       *
+       * @tparam Lhs_T Left-hand operand type.
+       * @tparam Rhs_T Right-hand operand type.
+       * @param op The greater-than-or-equal expression.
+       * @return Reference to this instance.
+       */
+      template <class Lhs_T, class Rhs_T>
+      expression_formatter&
+      operator<< (const detail::ge_<Lhs_T, Rhs_T>& op);
+
+      /**
+       * @brief Formats a less-than comparison as `lhs < rhs`.
+       *
+       * @tparam Lhs_T Left-hand operand type.
+       * @tparam Rhs_T Right-hand operand type.
+       * @param op The less-than expression.
+       * @return Reference to this instance.
+       */
+      template <class Lhs_T, class Rhs_T>
+      expression_formatter&
+      operator<< (const detail::lt_<Rhs_T, Lhs_T>& op);
+
+      /**
+       * @brief Formats a less-than-or-equal comparison as `lhs <= rhs`.
+       *
+       * @tparam Lhs_T Left-hand operand type.
+       * @tparam Rhs_T Right-hand operand type.
+       * @param op The less-than-or-equal expression.
+       * @return Reference to this instance.
+       */
+      template <class Lhs_T, class Rhs_T>
+      expression_formatter&
+      operator<< (const detail::le_<Rhs_T, Lhs_T>& op);
+
+      /**
+       * @brief Formats a logical AND as `(lhs and rhs)`.
+       *
+       * @tparam Lhs_T Left-hand operand type.
+       * @tparam Rhs_T Right-hand operand type.
+       * @param op The logical AND expression.
+       * @return Reference to this instance.
+       */
+      template <class Lhs_T, class Rhs_T>
+      expression_formatter&
+      operator<< (const detail::and_<Lhs_T, Rhs_T>& op);
+
+      /**
+       * @brief Formats a logical OR as `(lhs or rhs)`.
+       *
+       * @tparam Lhs_T Left-hand operand type.
+       * @tparam Rhs_T Right-hand operand type.
+       * @param op The logical OR expression.
+       * @return Reference to this instance.
+       */
+      template <class Lhs_T, class Rhs_T>
+      expression_formatter&
+      operator<< (const detail::or_<Lhs_T, Rhs_T>& op);
+
+      /**
+       * @brief Formats a logical NOT as `not operand`.
+       *
+       * @tparam T The operand type.
+       * @param op The logical NOT expression.
+       * @return Reference to this instance.
+       */
+      template <class T>
+      expression_formatter&
+      operator<< (const detail::not_<T>& op);
+
+#if defined(__cpp_exceptions)
+      /**
+       * @brief Formats a typed throws expression as
+       * `throws<TypeName>`.
+       *
+       * @tparam Callable_T The callable type.
+       * @tparam Exception_T The expected exception type.
+       * @param op The throws expression.
+       * @return Reference to this instance.
+       */
+      template <class Callable_T, class Exception_T>
+      expression_formatter&
+      operator<< (const detail::throws_<Callable_T, Exception_T>& op);
+
+      /**
+       * @brief Formats an untyped throws expression as `throws`.
+       *
+       * @tparam Callable_T The callable type.
+       * @param op The throws expression.
+       * @return Reference to this instance.
+       */
+      template <class Callable_T>
+      expression_formatter&
+      operator<< (const detail::throws_<Callable_T, void>& op);
+
+      /**
+       * @brief Formats a nothrow expression as `nothrow`.
+       *
+       * @tparam Callable_T The callable type.
+       * @param op The nothrow expression.
+       * @return Reference to this instance.
+       */
+      template <class Callable_T>
+      expression_formatter&
+      operator<< (const detail::nothrow_<Callable_T>& op);
+#endif
+
+      // ----------------------------------------------------------------------
+      // Buffer accessors.
+
+      /**
+       * @brief Returns a const reference to the internal buffer.
+       *
+       * @par Parameters
+       *   None.
+       * @return Const reference to the accumulated string.
+       */
+      [[nodiscard]] const std::string&
+      str () const noexcept;
+
+      /**
+       * @brief Returns a pointer to the null-terminated buffer contents.
+       *
+       * @par Parameters
+       *   None.
+       * @return Pointer to the null-terminated character array.
+       */
+      [[nodiscard]] const char*
+      c_str () const noexcept;
+
+      /**
+       * @brief Clears the internal buffer.
+       *
+       * @par Parameters
+       *   None.
+       * @par Returns
+       *   Nothing.
+       */
+      void
+      clear () noexcept;
+
+      /**
+       * @brief Returns whether the internal buffer is empty.
+       *
+       * @par Parameters
+       *   None.
+       * @retval true  The buffer contains no characters.
+       * @retval false The buffer contains at least one character.
+       */
+      [[nodiscard]] bool
+      empty () const noexcept;
+
+      /**
+       * @brief Appends a sequence of identical characters to the buffer.
+       *
+       * @param count The number of characters to append.
+       * @param ch The character to repeat.
+       * @par Returns
+       *   Nothing.
+       */
+      void
+      append (size_t count, char ch);
+
+      /**
+       * @brief Reserves storage in the internal buffer.
+       *
+       * @param capacity The minimum capacity to reserve.
+       * @par Returns
+       *   Nothing.
+       */
+      void
+      reserve (size_t capacity);
+
+    protected:
+      /**
+       * @brief Selects the appropriate colour code based on a condition.
+       *
+       * @param cond Boolean value indicating pass (true) or fail (false).
+       * @return The corresponding ANSI colour code as a string.
+       */
+      [[nodiscard]] inline auto
+      colour_ (const bool cond) const;
+
+      /**
+       * @brief ANSI colour codes for output formatting.
+       */
+      colours& colours_;
+
+      /**
+       * @brief The internal output buffer.
+       */
+      std::string buffer_{};
+    };
+
+    // ------------------------------------------------------------------------
+  } // namespace detail
+
+  // --------------------------------------------------------------------------
+} // namespace micro_os_plus::micro_test_plus
+
+#if defined(__GNUC__)
+#pragma GCC diagnostic pop
+#endif
+
+// ----------------------------------------------------------------------------
+
+#endif // __cplusplus
+
+// ============================================================================
+// Templates & constexpr implementations.
+
+#include "inlines/expression-formatter-inlines.h"
+
+// ----------------------------------------------------------------------------
+
+#endif // MICRO_TEST_PLUS_EXPRESSION_FORMATTER_H_
+
+// ----------------------------------------------------------------------------