From 3895f429f1947aac1d2465d89c7bcd3ce38fc70e Mon Sep 17 00:00:00 2001 From: 魏曹先生 <1992414357@qq.com> Date: Mon, 27 Jul 2026 21:04:50 +0800 Subject: docs(sidebar): archive resolved issues with _ prefix Archive three resolved issues by renaming files with an _ prefix and adding archival note banners --- docs/dev/pages/issues/remove-r-print-macro.md | 97 --------------------------- 1 file changed, 97 deletions(-) delete mode 100644 docs/dev/pages/issues/remove-r-print-macro.md (limited to 'docs/dev/pages/issues/remove-r-print-macro.md') diff --git a/docs/dev/pages/issues/remove-r-print-macro.md b/docs/dev/pages/issues/remove-r-print-macro.md deleted file mode 100644 index 43d2740..0000000 --- a/docs/dev/pages/issues/remove-r-print-macro.md +++ /dev/null @@ -1,97 +0,0 @@ -

Remove r_print! and r_println! Macros

- -`r_print!` and `r_println!` are important macros in Mingling for use inside `#[help]` and `#[renderer]` functions, but their implementation is not clean: they implicitly introduce a `__renderer_inner_result` field. While this might look elegant at the API level, it is **incorrect** and even **objectionable**. - -## Why **Objectionable**? - -Because you can't define declarative macros with `macro_rules` that wrap them. - -This is because `r_println!` depends on the implicit variable `__renderer_inner_result` injected by the `#[renderer]` proc macro into the function body. However, when a `macro_rules` declarative macro expands, **its internal code is placed in the caller's context**, which does not contain `__renderer_inner_result` — that variable only exists within the direct scope of the function body processed by `#[renderer]`. - -Let's look at some code to see why: - -```rust -// Suppose you want to write a wrapper macro: -macro_rules! my_println { - ($($arg:tt)*) => { - // When expanded here, the context is the call site of my_println!, - // not the location where the renderer function's injected variables live. - // So __renderer_inner_result is NOT visible here! - r_println!("Custom: {}", format!($($arg)*)); - }; -} - -#[renderer] -fn render_something(_p: ResultSomething) { - // Although this function body has __renderer_inner_result injected, - // the code from my_println! does NOT expand "inside this function body" — - // macro_rules expansion is essentially text replacement. The replaced code - // lives at the line where my_println! is called, and any variables referenced - // inside that macro must resolve to identifiers accessible at the call site. - // __renderer_inner_result is not a public, path-accessible variable; - // it's a hygienic local variable generated by the `#[renderer]` macro, - // and external macros cannot directly access it by name. - my_println!("{}", box_val); // Compile error: cannot find __renderer_inner_result -} -``` - -## Deeper Issues - -I have to admit, this is an early design flaw. After re-examining the code, I found the problem goes beyond "can't be wrapped". - -This isn't just a "can't wrap" issue — it reflects that `r_println!`'s design fundamentally violates Rust's macro hygiene principles: - -- **Implicit dependency**: Users of the macro must know that a variable named `__renderer_inner_result` exists — but this variable is neither part of the public API nor explicitly documented anywhere. -- **Scope leakage**: Variables injected by a proc macro should be confined to the scope processed by that macro. But `r_println!` attempts to make that variable accessible across macro calls, which effectively breaks Rust's identifier hygiene. -- **Non-composable**: Any attempt to wrap `r_println!` will fail, because declarative macros cannot "pass through" access to implicit variables. Even using a proc macro to wrap it would encounter similar hygiene issues. - -## Desired New Syntax - -I've designed two alternative approaches and will choose based on actual needs. - -### Option 1: Explicit Return - -```rust -#[renderer] -fn render_something(prev: ResultSomething) -> RenderResult { - let mut result = RenderResult::new(); - result.println(prev.to_string()); - // or - write!(result, "{}", prev.to_string()); - - result // return here -} -``` - -Clear boundaries — the entire rendering process is confined within the function body decorated by `#[help]` or `#[renderer]`, without introducing extra out-of-scope dependencies. The trade-off is slightly more boilerplate compared to the original approach. - -### Option 2: Resource Injection - -```rust -#[renderer] -fn render_something(prev: ResultSomething, result: &mut ResRenderResult) { - result.println(prev.to_string()); - // or - write!(result, "{}", prev.to_string()); - - result // return here -} -``` - -More flexible, but blurs the boundary between logic functions like `#[chain]` and rendering functions like `#[help]`. - -### Preferred Direction - -I lean toward **Option 1 (Explicit Return)**. There's no need to turn `RenderResult` into `ResRenderResult` as a global resource. - -As for rendering in logic functions like `#[chain]`, that should be handled by a separate system — not discussed here. - -## 🕘 Progress - -- [x] In Progress - - [x] Remove `r_println!` and `r_print!` macros - - [x] Modify `#[renderer]` and `#[help]` macros, remove implicit injection - - [x] Provide **no-return-value mode** and **RenderResult return value mode** for `#[renderer]` and `#[help]` macros - - [x] Add new simplified syntax - - [x] Update documentation and test cases, ensure **all pass** -- [x] Complete -- cgit