Patternia v0.5.2 Release Note

Release Date: December 10, 2025 Version: 0.5.2

---

Overview

Patternia v0.5.2 introduces the wildcard pattern __ and provides comprehensive documentation updates. This release focuses on semantic clarity, improved developer experience, and establishing a solid foundation for future exhaustiveness checking features.

---

New Features

Wildcard Pattern (__)

Added: ptn::__ - A pattern that matches any value without binding.

// Basic wildcard usage
match(value)
    .when(lit(0) >> "zero")
    .when(__ >> "other")  // Matches any other value
    .end();

Key Characteristics: - Always matches regardless of input value - Binds no data (returns empty tuple std::tuple<>) - More explicit than bind() when no capture is needed - Essential for catch-all cases and future struct destructuring

Enhanced Terminal Method Semantics

Improved: Clear distinction between .end() and .otherwise() terminal methods.

.end() - Statement-style Matching

• For void-returning matches (at v0.5.2; later versions allow non-void)
• Designed for exhaustiveness checking (future feature)
• Used when only side effects are needed

.otherwise(handler) - Expression-style Matching

• For value-returning matches
• Provides explicit fallback behavior
• Used when computing results from matches

Fallback Trigger Mechanism Clarification

Added: Detailed explanation of when .otherwise() is triggered:

1. No Pattern Matches: When no .when() cases match the subject
2. Defensive Fallback: Even with pattern coverage, provides runtime safety

Key Principle: First matching pattern wins, regardless of fallback types.

---

Documentation Improvements

Design Overview Document

Added: docs/design-overview.md - Comprehensive guide covering: - Three-level architecture (Pattern → Case → Match Finalizer) - Semantic differences between __, .end(), and .otherwise() - Usage scenarios and best practices - Implementation details and execution flow - Future roadmap for exhaustiveness checking

Enhanced API Reference

Updated: docs/api.md with: - Complete wildcard pattern documentation - Detailed comparison of terminal methods - Implementation notes about builder execution - Future features section with exhaustiveness checking roadmap

Improved User Guide

Updated: README.md featuring: - Wildcard pattern examples - Clear terminal method guidance - Future roadmap section - Better usage decision tables

---

Internal Improvements

Comment Standardization

Fixed: Consistent English comment style across all modified files: - include/ptn/pattern/wildcard.hpp - Added comprehensive file header - include/ptn/core/engine/detail/builder_impl.hpp - Completed member variable documentation - include/ptn/core/common/common_traits.hpp - Enhanced type trait comments - samples/test.cpp - Added explanatory comments and examples

Builder Implementation Enhancements

Improved: Better documentation in match_builder implementation: - Clear explanation of builder execution flow - Documented member variable purposes - Enhanced inline comments for complex template logic

---

Architecture Changes

Three-Level Design Formalization

Patternia now explicitly follows a three-level architecture:

1. Pattern Level: lit(), bind(), __, etc.
2. Case Level: .when(pattern >> handler)
3. Match Finalizer Level: .end() / .otherwise()

This design ensures: - Clear separation of concerns - Predictable behavior matching Rust/standard proposals - Extensible foundation for future features

Semantic Clarity Improvements

Established: Clear distinctions between: - Pattern-level wildcards (__) vs match-level fallbacks (.otherwise()) - Statement-style (.end()) vs expression-style (.otherwise()) matching - Field-level ignoring vs case-level fallbacks

---

Usage Examples

Basic Pattern Matching

#include <ptn/patternia.hpp>

// Expression-style match
auto result = match(value)
    .when(lit(1) >> "one")
    .when(lit(2) >> "two") 
    .when(__ >> "other")  // Wildcard fallback
    .otherwise("default");  // Match-level fallback

Statement-style Matching

// Statement-style match with exhaustiveness (future)
match(status)
    .when(lit(Status::Pending) >> [] { log("pending"); })
    .when(lit(Status::Running) >> [] { log("running"); })
    .when(__ >> [] { log("other"); })  // Pattern fallback
    .end();  // Statement termination

Enum with Wildcard

enum class Color { Red, Green, Blue };
Color c = Color::Green;

match(c)
    .when(lit(Color::Red) >> [] { std::cout << "red"; })
    .when(lit(Color::Green) >> [] { std::cout << "green"; })
    .when(__ >> [] { std::cout << "other"; })  // Catch-all
    .end();

---

Bug Fixes

API Clarity

Fixed: Ambiguous terminal method behavior - Clear distinction between .end() and .otherwise() - Better examples showing appropriate use cases