From 7b3a1d7fd9f60b91a7f9602374c081882d46facc Mon Sep 17 00:00:00 2001
From: 魏曹先生 <1992414357@qq.com>
Date: Mon, 20 Jul 2026 08:42:16 +0800
Subject: feat(macros): add `#[buffer]` attribute and re-export `r_print!(ln)`
 macros

Reintroduce `r_print!` and `r_println!` macros as public exports, now
supporting both explicit buffer argument and implicit `#[buffer]` attr.
Add `#[buffer]` attribute macro that wraps unit-returning functions to
produce a `RenderResult` with an automatically injected buffer variable.
Relax `RenderResult::print()` and `println()` to accept `impl
AsRef<str>`.
---
 CHANGELOG.md | 21 +++++++++++++++++----
 1 file changed, 17 insertions(+), 4 deletions(-)

(limited to 'CHANGELOG.md')

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b2fea6c..b90536e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -274,22 +274,35 @@ None
 
 #### **BREAKING CHANGES** (API CHANGES):
 
-1. **[`macros:renderer`]** **[`macros:help`]** Removed `r_println!` and `r_print!` macros. The `#[renderer]` and `#[help]` macros no longer implicitly inject an internal `RenderResult` variable or provide `r_println!` / `r_print!` macros.
+1. **[`macros:renderer`]** **[`macros:help`]** Removed `r_println!` and `r_print!` macros from being implicitly injected by `#[renderer]` and `#[help]` macros. These macros still exist, but must now be used **explicitly** — either with an explicit buffer argument, or via the `#[buffer]` extension attribute that re-enables implicit buffer injection.
 
-    Renderers and help functions must now explicitly create and return a `RenderResult`:
+    **Option A — Explicit buffer:** Pass a `RenderResult` variable as the first argument:
 
     ```rust
+    use mingling::macros::r_println;
     use mingling::prelude::*;
 
     #[renderer]
     fn render_greeting(greeting: ResultGreeting) -> RenderResult {
         let mut result = RenderResult::new();
-        writeln!(result, "Hello, {}!", *greeting).ok();
+        r_println!(result, "Hello, {}!", *greeting);
         result
     }
     ```
 
-    All examples, docs, and test cases across the repository have been updated to use the new pattern: creating a `RenderResult` with `RenderResult::new()` or `RenderResult::default()`, writing with `write!`/`writeln!` from `std::io::Write`, and returning the result.
+    **Option B — Implicit buffer via `#[buffer]` extension:** Use `#[renderer(buffer)]` to re-enable the old implicit injection behavior, where a `RenderResult` buffer is automatically created and `r_println!`/`r_print!` write to it without an explicit argument. This requires the function to return `()` (unit); the expanded function will return `RenderResult`:
+
+    ```rust
+    use mingling::macros::r_println;
+
+    #[renderer(buffer)]
+    fn render_greeting(greeting: ResultGreeting) {
+        r_println!("Hello, {}!", *greeting);
+        // Returns RenderResult implicitly
+    }
+    ```
+
+    The `#[buffer]` extension is also available standalone as `#[buffer]` for use outside of `#[renderer]`/`#[help]` functions.
 
 2. **[`macros:chain`]** The `#[chain]` macro's return type requirement has been relaxed. Previously, chain functions were required to return `Next` or `()` (with `()` auto-converting to `ResultEmpty`). Now, chain functions can also return `ChainProcess<ThisProgram>` directly, or omit the return type entirely (which defaults to `()` → `ResultEmpty`).
 
-- 
cgit