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

package/include/micro-os-plus/micro-test-plus/reporter.h

@@ -59,9 +59,12 @@
 #include <string>
 #include <memory>
 #include <vector>
+#include <charconv>
 
 #include "type-traits.h"
 #include "detail.h"
+#include "expression-formatter.h"
+#include "reflection.h"
 
 // ----------------------------------------------------------------------------
 
@@ -81,46 +84,6 @@ namespace micro_os_plus::micro_test_plus
 {
   // --------------------------------------------------------------------------
 
-  /**
-   * @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 The verbosity levels for test reporting.
    *
@@ -147,6 +110,8 @@ namespace micro_os_plus::micro_test_plus
   // Forward definitions.
   class reporter;
   class runner;
+  class suite;
+  class subtest;
 
   /**
    * @brief Output stream manipulator for ending a line in test reports.
@@ -158,17 +123,24 @@ namespace micro_os_plus::micro_test_plus
   reporter&
   endl (reporter& stream);
 
-  /**
-   * @brief Parameterised stream manipulator for outputting indentation.
-   *
-   * @details
-   * Holds the indentation level; used with `operator<<` on `reporter`
-   * so that `*this << indent(n) << "text"` works naturally in chains.
-   */
-  struct indent_t
+  namespace detail
   {
-    size_t level; /**< @brief Number of four-space indentation levels. */
-  };
+    // ------------------------------------------------------------------------
+
+    /**
+     * @brief Parameterised stream manipulator for outputting indentation.
+     *
+     * @details
+     * Holds the indentation level; used with `operator<<` on `reporter`
+     * so that `*this << indent(n) << "text"` works naturally in chains.
+     */
+    struct indent_t
+    {
+      size_t level; /**< @brief Number of four-space indentation levels. */
+    };
+
+    // ------------------------------------------------------------------------
+  } // namespace detail
 
   /**
    * @brief Factory function that creates an `indent_t` manipulator.
@@ -176,11 +148,10 @@ namespace micro_os_plus::micro_test_plus
    * @param level The number of four-space indentation levels.
    * @return An `indent_t` value for use with `operator<<`.
    */
-  [[nodiscard]] inline indent_t
-  indent (size_t level)
-  {
-    return { level };
-  }
+  [[nodiscard]] detail::indent_t
+  indent (size_t level);
+
+  // ==========================================================================
 
   /**
    * @brief Reporter to display test results, including operand values and
@@ -217,11 +188,6 @@ namespace micro_os_plus::micro_test_plus
     /**
      * @brief Constructor for the reporter class.
      *
-     * @details
-     * Parses the command-line arguments to determine the desired verbosity
-     * level and applies it to the reporter. The `--verbose`, `--quiet`, and
-     * `--silent` options are recognised.
-     *
      * @param argvs Owning pointer to the command-line arguments vector;
      * the reporter takes ownership via move.
      */
@@ -275,121 +241,17 @@ namespace micro_os_plus::micro_test_plus
     reporter& operator<< (std::nullptr_t);
 
     /**
-     * @brief Output operator for signed char values.
-     *
-     * @param c The signed char value to output.
-     * @return Reference to the current reporter instance.
-     */
-    reporter&
-    operator<< (signed char c);
-
-    /**
-     * @brief Output operator for unsigned char values.
-     *
-     * @param c The unsigned char value to output.
-     * @return Reference to the current reporter instance.
-     */
-    reporter&
-    operator<< (unsigned char c);
-
-    /**
-     * @brief Output operator for signed short values.
-     *
-     * @param v The signed short value to output.
-     * @return Reference to the current reporter instance.
-     */
-    reporter&
-    operator<< (signed short v);
-
-    /**
-     * @brief Output operator for unsigned short values.
-     *
-     * @param v The unsigned short value to output.
-     * @return Reference to the current reporter instance.
-     */
-    reporter&
-    operator<< (unsigned short v);
-
-    /**
-     * @brief Output operator for signed int values.
-     *
-     * @param v The signed int value to output.
-     * @return Reference to the current reporter instance.
-     */
-    reporter&
-    operator<< (signed int v);
-
-    /**
-     * @brief Output operator for unsigned int values.
+     * @brief Output operator for arithmetic types, with type suffixes.
      *
-     * @param v The unsigned int value to output.
-     * @return Reference to the current reporter instance.
-     */
-    reporter&
-    operator<< (unsigned int v);
-
-    /**
-     * @brief Output operator for signed long values.
-     *
-     * @param v The signed long value to output.
-     * @return Reference to the current reporter instance.
-     */
-    reporter&
-    operator<< (signed long v);
-
-    /**
-     * @brief Output operator for unsigned long values.
+     * @tparam T The arithmetic type.
      *
-     * @param v The unsigned long value to output.
-     * @return Reference to the current reporter instance.
-     */
-    reporter&
-    operator<< (unsigned long v);
-
-    /**
-     * @brief Output operator for signed long long values.
-     *
-     * @param v The signed long long value to output.
-     * @return Reference to the current reporter instance.
-     */
-    reporter&
-    operator<< (signed long long v);
-
-    /**
-     * @brief Output operator for unsigned long long values.
-     *
-     * @param v The unsigned long long value to output.
-     * @return Reference to the current reporter instance.
-     */
-    reporter&
-    operator<< (unsigned long long v);
-
-    /**
-     * @brief Output operator for float values.
-     *
-     * @param v The float value to output.
-     * @return Reference to the current reporter instance.
-     */
-    reporter&
-    operator<< (float v);
-
-    /**
-     * @brief Output operator for double values.
-     *
-     * @param v The double value to output.
-     * @return Reference to the current reporter instance.
-     */
-    reporter&
-    operator<< (double v);
-
-    /**
-     * @brief Output operator for long double values.
-     *
-     * @param v The long double value to output.
+     * @param v The value to output.
      * @return Reference to the current reporter instance.
      */
+    template <class T>
+      requires std::is_arithmetic_v<T>
     reporter&
-    operator<< (long double v);
+    operator<< (T v);
 
     /**
      * @brief Output operator to display any pointer.
@@ -415,202 +277,6 @@ namespace micro_os_plus::micro_test_plus
     // ------------------------------------------------------------------------
     // Specific operators.
 
-    /**
-     * @brief Output operator for types with a getter.
-     *
-     * @tparam T The type with a getter method.
-     *
-     * @param t The object to output.
-     * @return Reference to the current reporter instance.
-     */
-    template <class T>
-      requires type_traits::is_op<T>
-    reporter&
-    operator<< (const T& t);
-
-    /**
-     * @brief Output operator to display genuine integers, without the type
-     * suffix.
-     *
-     * @tparam T The underlying integral type.
-     *
-     * @param v The strongly-typed integral value to output.
-     * @return Reference to the current reporter instance.
-     */
-    template <class T>
-    reporter&
-    operator<< (const type_traits::genuine_integral_value<T>& v);
-
-    /**
-     * @brief Output operator to display containers. Iterates all members.
-     *
-     * @tparam T The container type.
-     *
-     * @param t The container to output.
-     * @return Reference to the current reporter instance.
-     */
-    template <class T>
-      requires (type_traits::container_like<T>
-                and not type_traits::has_npos<T>)
-    reporter&
-    operator<< (const T& t);
-
-    /**
-     * @brief Output operator to display eq() expressions.
-     *
-     * @tparam Lhs_T The left-hand side type.
-     * @tparam Rhs_T The right-hand side type.
-     *
-     * @param op The equality comparator expression.
-     * @return Reference to the current reporter instance.
-     */
-    template <class Lhs_T, class Rhs_T>
-    reporter&
-    operator<< (const detail::eq_<Lhs_T, Rhs_T>& op);
-
-    /**
-     * @brief Output operator to display ne() expressions.
-     *
-     * @tparam Lhs_T The left-hand side type.
-     * @tparam Rhs_T The right-hand side type.
-     *
-     * @param op The inequality comparator expression.
-     * @return Reference to the current reporter instance.
-     */
-    template <class Lhs_T, class Rhs_T>
-    reporter&
-    operator<< (const detail::ne_<Lhs_T, Rhs_T>& op);
-
-    /**
-     * @brief Output operator to display gt() expressions.
-     *
-     * @tparam Lhs_T The left-hand side type.
-     * @tparam Rhs_T The right-hand side type.
-     *
-     * @param op The greater-than comparator expression.
-     * @return Reference to the current reporter instance.
-     */
-    template <class Lhs_T, class Rhs_T>
-    reporter&
-    operator<< (const detail::gt_<Lhs_T, Rhs_T>& op);
-
-    /**
-     * @brief Output operator to display ge() expressions.
-     *
-     * @tparam Lhs_T The left-hand side type.
-     * @tparam Rhs_T The right-hand side type.
-     *
-     * @param op The greater-than-or-equal-to comparator expression.
-     * @return Reference to the current reporter instance.
-     */
-    template <class Lhs_T, class Rhs_T>
-    reporter&
-    operator<< (const detail::ge_<Lhs_T, Rhs_T>& op);
-
-    /**
-     * @brief Output operator to display lt() expressions.
-     *
-     * @tparam Lhs_T The left-hand side type.
-     * @tparam Rhs_T The right-hand side type.
-     *
-     * @param op The less-than comparator expression.
-     * @return Reference to the current reporter instance.
-     */
-    template <class Lhs_T, class Rhs_T>
-    reporter&
-    operator<< (const detail::lt_<Rhs_T, Lhs_T>& op);
-
-    /**
-     * @brief Output operator to display le() expressions.
-     *
-     * @tparam Lhs_T The left-hand side type.
-     * @tparam Rhs_T The right-hand side type.
-     *
-     * @param op The less-than-or-equal-to comparator expression.
-     * @return Reference to the current reporter instance.
-     */
-    template <class Lhs_T, class Rhs_T>
-    reporter&
-    operator<< (const detail::le_<Rhs_T, Lhs_T>& op);
-
-    /**
-     * @brief Output operator to display and() expressions.
-     *
-     * @tparam Lhs_T The left-hand side type.
-     * @tparam Rhs_T The right-hand side type.
-     *
-     * @param op The logical conjunction (AND) expression.
-     * @return Reference to the current reporter instance.
-     */
-    template <class Lhs_T, class Rhs_T>
-    reporter&
-    operator<< (const detail::and_<Lhs_T, Rhs_T>& op);
-
-    /**
-     * @brief Output operator to display or() expressions.
-     *
-     * @tparam Lhs_T The left-hand side type.
-     * @tparam Rhs_T The right-hand side type.
-     *
-     * @param op The logical disjunction (OR) expression.
-     * @return Reference to the current reporter instance.
-     */
-    template <class Lhs_T, class Rhs_T>
-    reporter&
-    operator<< (const detail::or_<Lhs_T, Rhs_T>& op);
-
-    /**
-     * @brief Output operator to display not() expressions.
-     *
-     * @tparam T The operand type.
-     *
-     * @param op The logical negation expression.
-     * @return Reference to the current reporter instance.
-     */
-    template <class T>
-    reporter&
-    operator<< (const detail::not_<T>& op);
-
-#if defined(__cpp_exceptions)
-    /**
-     * @brief Output operator to display throws expressions for a specific
-     * exception type.
-     *
-     * @tparam Expr_T The expression type.
-     * @tparam Exception_T The exception type.
-     *
-     * @param op The throws comparator expression.
-     * @return Reference to the current reporter instance.
-     */
-    template <class Expr_T, class Exception_T>
-    reporter&
-    operator<< (const detail::throws_<Expr_T, Exception_T>& op);
-
-    /**
-     * @brief Output operator to display throws expressions for any exception.
-     *
-     * @tparam Expr_T The expression type.
-     *
-     * @param op The throws comparator expression.
-     * @return Reference to the current reporter instance.
-     */
-    template <class Expr_T>
-    reporter&
-    operator<< (const detail::throws_<Expr_T, void>& op);
-
-    /**
-     * @brief Output operator to display nothrow expressions.
-     *
-     * @tparam Expr_T The expression type.
-     *
-     * @param op The nothrow comparator expression.
-     * @return Reference to the current reporter instance.
-     */
-    template <class Expr_T>
-    reporter&
-    operator<< (const detail::nothrow_<Expr_T>& op);
-#endif
-
     // ------------------------------------------------------------------------
 
     /**
@@ -656,35 +322,33 @@ namespace micro_os_plus::micro_test_plus
     /**
      * @brief Report a passed condition.
      *
-     * @tparam Expr_T The expression type.
-     *
-     * @param expr The evaluated expression.
      * @param message The message to display.
+     * @param expression The string representation of the expression.
      * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
-    template <class Expr_T>
     void
-    pass (Expr_T& expr, std::string& message, subtest& subtest);
+    pass (std::string& message, const std::string& expression,
+          subtest& subtest);
 
     /**
      * @brief Report a failed condition.
      *
-     * @tparam Expr_T The expression type.
-     *
-     * @param expr The evaluated expression.
      * @param abort Whether to abort execution after failure.
      * @param message The message to display.
+     * @param expression The string representation of the expression.
+     * @param has_expression Whether the expression is a compound op to
+     * display.
      * @param location The source location of the failure.
      * @param subtest The subtest that owns this check.
      * @par Returns
      *   Nothing.
      */
-    template <class Expr_T>
     void
-    fail (Expr_T& expr, bool abort, std::string& message,
-          const reflection::source_location& location, subtest& subtest);
+    fail (bool abort, std::string& message, const std::string& expression,
+          bool has_expression, const reflection::source_location& location,
+          subtest& subtest);
 
     // ------------------------------------------------------------------------
 
@@ -696,7 +360,8 @@ namespace micro_os_plus::micro_test_plus
      *   Nothing.
      */
     virtual void
-    begin_session (runner& runner) = 0;
+    begin_session (runner& runner)
+        = 0;
 
     /**
      * @brief Mark the end of a test session.
@@ -706,7 +371,8 @@ namespace micro_os_plus::micro_test_plus
      *   Nothing.
      */
     virtual void
-    end_session (runner& runner) = 0;
+    end_session (runner& runner)
+        = 0;
 
     /**
      * @brief Mark the beginning of a test suite.
@@ -716,7 +382,8 @@ namespace micro_os_plus::micro_test_plus
      *   Nothing.
      */
     virtual void
-    begin_suite (suite& suite) = 0;
+    begin_suite (suite& suite)
+        = 0;
 
     /**
      * @brief Mark the end of a test suite.
@@ -726,7 +393,8 @@ namespace micro_os_plus::micro_test_plus
      *   Nothing.
      */
     virtual void
-    end_suite (suite& suite) = 0;
+    end_suite (suite& suite)
+        = 0;
 
     /**
      * @brief Mark the beginning of a subtest.
@@ -736,7 +404,8 @@ namespace micro_os_plus::micro_test_plus
      *   Nothing.
      */
     virtual void
-    begin_subtest (subtest& subtest) = 0;
+    begin_subtest (subtest& subtest)
+        = 0;
 
     /**
      * @brief Mark the end of a subtest.
@@ -746,21 +415,19 @@ namespace micro_os_plus::micro_test_plus
      *   Nothing.
      */
     virtual void
-    end_subtest (subtest& subtest) = 0;
+    end_subtest (subtest& subtest)
+        = 0;
 
     /**
      * @brief Returns the comment-prefix string used by this reporter format.
      *
-     * @details
-     * Human reporters return an empty string; TAP reporters return `"# "`
-     * so that diagnostic lines conform to the TAP specification.
-     *
      * @par Parameters
      *	 None.
      * @return A null-terminated prefix string.
      */
     virtual const char*
-    get_comment_prefix (void) = 0;
+    get_comment_prefix (void)
+        = 0;
 
     /**
      * @brief Returns the current verbosity level.
@@ -770,10 +437,18 @@ namespace micro_os_plus::micro_test_plus
      * @return The active `verbosity` value.
      */
     auto
-    verbosity () const -> micro_test_plus::verbosity
-    {
-      return verbosity_;
-    }
+    verbosity () const -> micro_test_plus::verbosity;
+
+    /**
+     * @brief Provides access to the expression formatter for this reporter.
+     *
+     * @par Parameters
+     *	 None.
+     * @return Reference to the `expression_formatter` instance used by this
+     * reporter.
+     */
+    detail::expression_formatter&
+    expression ();
 
     // ------------------------------------------------------------------------
 
@@ -783,16 +458,9 @@ namespace micro_os_plus::micro_test_plus
      *
      * @param cond Boolean value indicating pass (true) or fail (false).
      * @return The corresponding ANSI colour code as a string.
-     *
-     * @details
-     * Returns the ANSI colour code for pass or fail, depending on the boolean
-     * condition provided.
      */
     [[nodiscard]] inline auto
-    colour_ (const bool cond) const
-    {
-      return cond ? colours_.pass : colours_.fail;
-    }
+    colour_ (const bool cond) const;
 
     void
     write_buffer_to_file_ (void);
@@ -817,7 +485,8 @@ namespace micro_os_plus::micro_test_plus
      *   Nothing.
      */
     virtual void
-    output_pass_prefix_ (std::string& message, subtest& subtest) = 0;
+    output_pass_prefix_ (std::string& message, subtest& subtest)
+        = 0;
 
     /**
      * @brief Outputs the suffix for a passing condition.
@@ -827,13 +496,14 @@ namespace micro_os_plus::micro_test_plus
      *   Nothing.
      */
     virtual void
-    output_pass_suffix_ (subtest& subtest) = 0;
+    output_pass_suffix_ (subtest& subtest)
+        = 0;
 
     /**
      * @brief Outputs the prefix for a failing condition.
      *
      * @param message The message to display.
-     * @param hasExpression Whether the failure is associated with an
+     * @param has_expression Whether the failure is associated with an
      * expression.
      * @param location The source location of the failure.
      * @param subtest The subtest that owns this check.
@@ -841,9 +511,10 @@ namespace micro_os_plus::micro_test_plus
      *   Nothing.
      */
     virtual void
-    output_fail_prefix_ (std::string& message, const bool hasExpression,
+    output_fail_prefix_ (std::string& message, const bool has_expression,
                          const reflection::source_location& location,
-                         subtest& subtest) = 0;
+                         subtest& subtest)
+        = 0;
 
     /**
      * @brief Outputs the suffix for a failing condition.
@@ -856,23 +527,8 @@ namespace micro_os_plus::micro_test_plus
      */
     virtual void
     output_fail_suffix_ (const reflection::source_location& location,
-                         bool abort, subtest& subtest) = 0;
-
-    /**
-     * @brief Appends the string representation of a numeric value to a
-     * buffer, using `std::to_chars` for allocation-free, locale-independent
-     * formatting.
-     *
-     * @tparam T The numeric type to format.
-     *
-     * @param buffer The string to append to.
-     * @param v The value to format.
-     * @par Returns
-     *   Nothing.
-     */
-    template <class T>
-    static void
-    append_number_ (std::string& buffer, T v);
+                         bool abort, subtest& subtest)
+        = 0;
 
   protected:
     /**
@@ -883,13 +539,29 @@ namespace micro_os_plus::micro_test_plus
     /**
      * @brief ANSI colour codes for output formatting.
      */
-    colours colours_{};
+    detail::colours colours_{};
 
     /**
-     * @brief Internal output buffer for accumulating report content.
+     * @brief Output accumulation buffer.
+     *
+     * @details
+     * Accumulates all reporter output until it is written to standard
+     * output or the output file via `write_buffer_to_stdout()` or
+     * `write_buffer_to_file_()`.
      */
     std::string buffer_{};
 
+    /**
+     * @brief Expression formatter for pass and fail reporting.
+     *
+     * @details
+     * Used in `pass()` and `fail()` to format expression values before
+     * appending the result to `buffer_`. Will also be used by
+     * `detail::deferred_reporter` to pre-format expressions at
+     * construction time.
+     */
+    detail::expression_formatter expression_{ colours_ };
+
     /**
      * @brief Controls whether to add an empty line between successful test
      * cases.
@@ -935,6 +607,11 @@ namespace micro_os_plus::micro_test_plus
 
 #endif // __cplusplus
 
+// ============================================================================
+// Templates & constexpr implementations.
+
+#include "inlines/reporter-inlines.h"
+
 // ----------------------------------------------------------------------------
 
 #endif // MICRO_TEST_PLUS_TEST_REPORTER_H_