[Discussion] Macro System Refactoring - Reducing Complexity While Maintaining Core Functionality

Following discussion started here #54 (comment) with @jasmcaus

Purpose

This issue aims to provide a starting point for a constructive discussion about potential refactoring of Tau's macro system. The ideas presented here are intended as brainstorming contributions and exploratory thoughts, not as firm positions or mandatory changes to implement. The goal is to facilitate dialogue around maintaining Tau's core philosophy while addressing complexity concerns.

What Makes Tau Great

Before discussing potential improvements, it's worth highlighting what makes Tau exceptional compared to other unit testing frameworks:

• Simplicity of use: Single header-only design with no need to build libraries or use external scripts (like Ruby) for fixture setup
• Clarity and effectiveness: Provides exactly the macros developers need with meaningful error information when tests fail
• Aesthetic excellence: Beautiful colored output with clear failure indication that enhances the development experience

Areas for Potential Improvement

1. Output Enhancement

String and Buffer Comparison Clarity

Currently, string and buffer comparison macros don't provide developers with a clear view of expected vs. actual values. For example, with *_*EQ operations, the output shows:

• expected: str1==str2
• actual: not equal

A clearer approach might be:

• expected: str2
• actual: xxx

While maintaining the existing highlighting of differing parts.

Output Consistency

Consider applying greater uniformity to string and buffer comparison outputs. For instance, buffer comparisons could adopt the same highlighting style recently introduced for strings (inverting color and background for differing bytes).

2. Backward Compatibility Strategy

In the event of breaking changes, consider providing a compatibility header (e.g., tau_legacy.h) that offers a conversion interface to maintain backward compatibility for existing codebases.

3. Modular Header Architecture

Consider implementing an optional additional header approach:

• tau.h would contain core features
• tau_ex.h (which includes tau.h) would provide extended functionality

This would allow developers to choose their desired feature set while maintaining the "tiny" philosophy for the core.

4. Macro Reduction Considerations

Identifying candidates for macro elimination is challenging since most macros serve distinct purposes in practice. Potential considerations:

Less-Than-or-Equal / Greater-Than-or-Equal Macros

Consider removing CHECK_LE(a,b) and CHECK_GE(a,b) in favor of CHECK_TRUE(a <= b) and CHECK_TRUE(a >= b). Benefits include:

• Better feedback: CHECK_TRUE(a <= b) shows the exact condition that failed
• Enhanced expressivity: Developers can choose between a <= b vs a < b semantically
• Reduced macro count: Eliminates macros that don't add significant value over CHECK_TRUE

Less-Than / Greater-Than Comparison Macros

Similarly, CHECK_LT(a,b) and CHECK_GT(a,b) could be replaced with CHECK_TRUE(a < b) and CHECK_TRUE(a > b) respectively, maintaining the same level of clarity while further reducing the macro count.

Not-Equal Comparison Macro

Consider removing CHECK_NE(a,b) which can be replaced with CHECK_TRUE(a != b) or CHECK_FALSE(a == b). Both alternatives provide equivalent feedback quality while reducing macro proliferation.

Pointer Comparison Macros

The pointer comparison macros might be candidates for removal, as they could theoretically be replaced with CHECK_EQ((void*)ptr1, (void*)ptr2). However, this would result in the loss of hexadecimal address representation in expected/actual output (addresses would display as decimal numbers instead).

5. Naming Convention Refinement

The current naming approach successfully achieves compact, clear naming. Further length reduction seems unlikely without sacrificing clarity. However, if slightly improved readability is desired, consider standardizing the naming pattern:

Current mixed approach:

• CHECK_BUF_EQ (with underscores)
• CHECK_STREQ (without underscores)

Potential standardized approach:

• CHECK_BUF_EQ
• CHECK_STR_EQ (for consistency)

Discussion Points

1. Core vs. Extended Features: Which macros are truly essential for the core framework vs. which could be moved to an extended header?

2. Breaking Change Tolerance: What level of breaking changes would be acceptable for significant complexity reduction?

3. Output Improvements: Are the suggested output enhancements aligned with the project's philosophy?

4. Naming Consistency: Is standardizing the naming convention worth potential breaking changes?

5. Future Extensibility: How can we design the refactored system to be more maintainable while preserving the "tiny" ethos?

Next Steps

This issue is intended to gather thoughts and opinions from maintainers and users before any implementation work begins. All feedback, concerns, and alternative approaches are welcome and appreciated.

Note: The observations and suggestions above come from practical usage of Tau in production systems and are offered in the spirit of collaborative improvement.