miniextendr_macros/

method_return_builder.rs

//! Shared utilities for handling method return values in R wrapper generation.
//!
//! This module provides helpers for generating consistent return value handling
//! across all class systems (Env, R6, S7, S3, S4).

use crate::miniextendr_impl::ParsedMethod;
use crate::miniextendr_impl::ReceiverKind;

// region: Shared R error-check helpers
//
// All wrappers route through the internal helper `.miniextendr_raise_condition`
// emitted once at the top of the generated wrappers file (see
// `miniextendr-api/src/registry.rs` `write_r_wrappers_to_file`). The helper
// performs the `.val$kind` dispatch and `rust_*` class layering; each wrapper
// only needs a one-line guard at the call site.

/// Generate the R guard that re-raises a tagged Rust error/condition value.
///
/// Expects `.val` to already be assigned (e.g., `.val <- .Call(...)`). Emits a
/// single line indented by `indent`: when `.val` is a tagged `rust_condition_value`,
/// hand off to the shared helper and return from the enclosing function.
///
/// The helper dispatches on `.val$kind` (see
/// `miniextendr_api::error_value::kind` for canonical kind strings):
///
/// - `error` / `panic` / `result_err` / `none_err` / `conversion` (and any
///   unknown kind) — `stop()` longjmps with the appropriate `rust_*` class
///   layering.
/// - `warning` — `warning()` signals; the wrapper's surrounding `return(...)`
///   propagates `invisible(NULL)` as the wrapper's result.
/// - `message` — `message()` signals; same propagation.
/// - `condition` — `signalCondition()` signals; same propagation.
pub fn condition_check_lines(indent: &str) -> Vec<String> {
    condition_check_lines_with_default(indent, "sys.call()")
}

/// [`condition_check_lines`] with an explicit raise fallback
/// (`CallAttribution::raise_default`): `environment()` for an S3 method, whose
/// frame the raise helper turns into the generic's call (#1851).
pub fn condition_check_lines_with_default(indent: &str, raise_default: &str) -> Vec<String> {
    vec![format!(
        "{indent}if (inherits(.val, \"rust_condition_value\") && isTRUE(attr(.val, \"__rust_condition__\"))) return(.miniextendr_raise_condition(.val, {raise_default}))"
    )]
}

/// Generate an inline R error-check block for single-expression contexts (S7, S4).
///
/// Returns a multi-line block string: `{ .val <- <call_expr>; if (...) return(...); <inner> }`.
/// Used where the class system requires a single expression rather than separate lines
/// (e.g., S7 property definitions, S4 method bodies).
///
/// - `call_expr`: The `.Call()` expression to evaluate
/// - `inner`: The final expression to return after the error check passes
/// - `indent`: Leading whitespace for the inner lines (e.g., `"    "` for 4-space)
pub fn condition_check_inline_block(call_expr: &str, inner: &str, indent: &str) -> String {
    format!(
        "{{\n{indent}.val <- {call_expr}\n\
         {indent}if (inherits(.val, \"rust_condition_value\") && isTRUE(attr(.val, \"__rust_condition__\"))) return(.miniextendr_raise_condition(.val, sys.call()))\n\
         {indent}{inner}\n  \
         }}"
    )
}

/// Generate a standalone-function R wrapper body.
///
/// Returns the full body string: `.val <- <call_expr>; if (...) return(...); <final_return>`.
/// Used for top-level `#[miniextendr]` functions (not class methods).
///
/// - `call_expr`: The `.Call()` expression to evaluate
/// - `final_return`: The expression to return (typically `".val"` or `"invisible(.val)"`)
/// - `indent`: Leading whitespace for the body lines (e.g., `"  "` for 2-space)
pub fn standalone_body(call_expr: &str, final_return: &str, indent: &str) -> String {
    standalone_body_with_call_default(call_expr, final_return, indent, "sys.call()")
}

/// [`standalone_body`] with an explicit raise fallback: `sys.call()` for the
/// wrapper's own frame, `.mx_call` for `call = caller` wrappers, `NULL` under
/// `call = none` and `environment()` for an S3 method (see
/// `crate::r_wrapper_builder::CallAttribution::raise_default`).
pub fn standalone_body_with_call_default(
    call_expr: &str,
    final_return: &str,
    indent: &str,
    call_default: &str,
) -> String {
    format!(
        ".val <- {call_expr}\n\
         {indent}if (inherits(.val, \"rust_condition_value\") && isTRUE(attr(.val, \"__rust_condition__\"))) return(.miniextendr_raise_condition(.val, {call_default}))\n\
         {indent}{final_return}"
    )
}
// endregion

// region: Return strategy

/// Return handling strategy for class methods.
///
/// Determines how the R wrapper function processes and returns the `.Call()` result.
/// Each class system generator uses this to produce idiomatic R return code.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ReturnStrategy {
    /// The method returns `Self`. The wrapper wraps the raw pointer result with
    /// the appropriate class attribute or creates a new class object (e.g.,
    /// `R6Class$new(.ptr = result)` or `structure(result, class = "...")`).
    ReturnSelf,
    /// The method returns a bare type name that may be another registered
    /// ExternalPtr-backed class. The final decision is deferred to
    /// `write_r_wrappers_to_file`, where the complete class registry is known.
    ReturnOtherClass,
    /// The method returns a *list* of values (`Vec<Class>`, plus its
    /// `Option<Vec<Class>>` / `Result<Vec<Class>, E>` wrappers; an `Option`'s
    /// `NULL` passes through the wrap) whose element type may be another registered
    /// ExternalPtr-backed class (#1284). Deferred to `write_r_wrappers_to_file`
    /// like [`ReturnOtherClass`](Self::ReturnOtherClass), but through a
    /// distinct `.__MX_WRAP_LIST_RETURN_*` marker that resolves to a per-element
    /// `lapply(...)` wrap. The marker prefix must never overlap the scalar
    /// `.__MX_WRAP_RETURN_` family: the scalar resolver rewrites unrecognized
    /// markers of its own prefix to the bare expression, so a shared prefix
    /// would consume list markers before the list resolver ran.
    ReturnOtherClassList,
    /// The method is a `&mut self` method returning `()`. The wrapper calls the
    /// `.Call()` for its side effect and returns the receiver (`self`/`x`) for
    /// method chaining. The receiver is returned visibly unless the method is
    /// marked `Invisible<..>` / `invisible` (#1213).
    ChainableMutation,
    /// Default strategy: return the `.Call()` result directly without wrapping.
    Direct,
}

impl ReturnStrategy {
    /// Determine the return strategy for a parsed method.
    ///
    /// - Methods that return `Self`, `Result<Self, E>`, or `Option<Self>` use
    ///   `ReturnSelf`. The C wrapper already raised on `Err` (see
    ///   [`crate::c_wrapper_builder::ReturnHandling::ResultExternalPtr`]) and
    ///   gives `NULL` for `None` (see
    ///   [`crate::c_wrapper_builder::ReturnHandling::OptionExternalPtr`]), which
    ///   passes through; any other `.val` is a bare ExternalPtr — identical in
    ///   shape to the bare-`Self` case — and gets the same class-wrapping tail.
    /// - In-place builders (`&mut self -> &mut Self` / `&self -> Self`) and
    ///   `&mut self -> ()` methods use `ChainableMutation`. Both return the
    ///   receiver object (`x` / `self`, visibly unless marked invisible) so the
    ///   call composes under the native pipe (`obj |> set_a(1) |> set_b(2)`);
    ///   the C wrapper hands back the same ExternalPtr handle (see
    ///   [`crate::c_wrapper_builder::ReturnHandling::SelfHandle`]).
    ///
    /// A visibility marker on the return type (`Invisible<Self>`,
    /// `Invisible<()>`, ...) is peeled at parse time
    /// ([`ParsedMethod::sig`] holds the inner type), so it never changes the
    /// strategy; it only sets [`MethodReturnBuilder::with_invisible`].
    /// - Bare capitalized return types that are not known primitives/containers
    ///   use `ReturnOtherClass`; write-time registry lookup wraps registered
    ///   classes and leaves false positives unchanged. This also covers the
    ///   explicit-handle spelling `ExternalPtr<Class>` (#1375) — the detector
    ///   peels through it to the same wrapped name.
    /// - `Vec<Class>` (and its `Option`/`Result` wrappers; an `Option` return's
    ///   `NULL` passes through) use `ReturnOtherClassList`; write-time registry lookup wraps
    ///   registered element classes via `lapply` and leaves false positives
    ///   unchanged (#1284). This also covers `Vec<ExternalPtr<Class>>` and
    ///   `Vec<Self>` (#1375) — the latter via `returns_self_list()`, since the
    ///   scalar detector can't name `Self`;
    ///   `with_return_class_from_method` substitutes the actual name.
    /// - All other methods use `Direct`.
    pub fn for_method(method: &ParsedMethod) -> Self {
        // In-place builders (`&mut self -> &mut Self` / `&self -> Self`), their
        // fallible forms (`-> Result<&mut Self, E>` / `Option<&mut Self>`, #1433),
        // `&mut self -> ()` mutators, and consuming steps (`self -> Self` /
        // `Result<Self, E>` / `Option<Self>`, #1432: the C wrapper writes the
        // result back into the same handle) all return the receiver object.
        let is_self_ref_builder = method.env.is_instance()
            && (method.returns_self_ref()
                || method.returns_result_self_ref()
                || method.returns_option_self_ref());
        let is_unit_mutator = method.env.is_mut() && method.returns_unit();
        let returns_self_shaped =
            method.returns_self() || method.returns_result_self() || method.returns_option_self();
        let is_consuming_builder = method.env == ReceiverKind::Value && returns_self_shaped;
        if is_consuming_builder || is_self_ref_builder || is_unit_mutator {
            ReturnStrategy::ChainableMutation
        } else if returns_self_shaped {
            ReturnStrategy::ReturnSelf
        } else if method.returns_other_class().is_some() {
            ReturnStrategy::ReturnOtherClass
        } else if method.returns_other_class_list().is_some() || method.returns_self_list() {
            ReturnStrategy::ReturnOtherClassList
        } else {
            ReturnStrategy::Direct
        }
    }
}

/// Class-specific tail closures, one per [`ReturnStrategy`] variant.
///
/// Each closure receives `(indent, class_name)` and produces the tail lines that
/// run after `.val <- <call_expr>` and the condition check (both emitted by
/// [`MethodReturnBuilder::build_with_tails`]). The tail therefore always
/// references `.val` directly.
///
/// `class_name` is `""` for [`ReturnStrategy::ChainableMutation`],
/// [`ReturnStrategy::ReturnOtherClass`],
/// [`ReturnStrategy::ReturnOtherClassList`], and [`ReturnStrategy::Direct`] —
/// those tails should not use it.
#[allow(clippy::type_complexity)]
struct ReturnTails<'a> {
    /// Tail for [`ReturnStrategy::ReturnSelf`].
    ///
    /// Parameters: `(indent, class_name) -> lines`
    self_tail: Box<dyn Fn(&str, &str) -> Vec<String> + 'a>,
    /// Tail for [`ReturnStrategy::ChainableMutation`].
    ///
    /// Parameters: `(indent) -> lines`
    chain_tail: Box<dyn Fn(&str) -> Vec<String> + 'a>,
    /// Tail for [`ReturnStrategy::Direct`].
    ///
    /// Parameters: `(indent) -> lines`
    direct_tail: Box<dyn Fn(&str) -> Vec<String> + 'a>,
}

/// Builder for generating R method body lines with appropriate return handling.
///
/// Produces lines of R code for a method body, combining the `.Call()` expression
/// with the return strategy and the tagged-condition error guard. Each class
/// system has specialized builder methods (`build_r6_body`, `build_s3_body`,
/// etc.) that produce idiomatic R code for that system.
pub struct MethodReturnBuilder {
    /// The `.Call()` expression string (e.g., `".Call(C_Counter__inc, .call = sys.call(), self)"`).
    call_expr: String,
    /// How to handle the return value (direct, chaining, or Self wrapping).
    strategy: ReturnStrategy,
    /// R class name, required when `strategy` is `ReturnSelf` to construct
    /// the class wrapper (e.g., `"Counter"` for `Counter$new(.ptr = result)`).
    class_name: Option<String>,
    /// Rust return type name, required when `strategy` is `ReturnOtherClass`
    /// or `ReturnOtherClassList` (the element type in the list case). The
    /// write-time resolver maps this Rust name to the registered target class
    /// and constructor syntax, or falls back to the bare value on miss.
    return_class: Option<String>,
    /// Explicit constructor selection, before automatic return-shape tails.
    explicit_wrap: Option<crate::return_wrap::ReturnWrap>,
    /// The method returns `Option<..>`, so `.val` is `NULL` for `None` (the C
    /// wrapper converts the whole `Option`, as a function's does): the class
    /// wrap or receiver passes it through instead of constructing from it.
    nullable: bool,
    /// Variable name to return for `ChainableMutation` strategy (e.g., `"self"` for R6,
    /// `"x"` for S3). Defaults to `"self"` if not set.
    chain_var: Option<String>,
    /// Wrap the final expression in `invisible(...)` (#1213). Set from a
    /// return-type marker (`Invisible<T>`) or the `invisible` method option;
    /// nothing is invisible by default.
    invisible: bool,
    /// Number of leading spaces for each generated line.
    indent: usize,
    /// The raise helper's fallback call (`CallAttribution::raise_default`):
    /// `sys.call()` unless set, `environment()` for an S3 method (#1851).
    raise_default: String,
}

impl MethodReturnBuilder {
    /// Create a new builder with the given .Call expression.
    pub fn new(call_expr: String) -> Self {
        Self {
            call_expr,
            strategy: ReturnStrategy::Direct,
            class_name: None,
            return_class: None,
            explicit_wrap: None,
            nullable: false,
            chain_var: None,
            invisible: false,
            indent: 2,
            raise_default: "sys.call()".to_string(),
        }
    }

    /// Set the raise helper's fallback call (see
    /// `CallAttribution::raise_default`).
    pub fn with_raise_default(mut self, raise_default: &str) -> Self {
        self.raise_default = raise_default.to_string();
        self
    }

    /// Wrap the method's final expression in `invisible(...)` (marker or
    /// `invisible` option, see [`ParsedMethod::is_invisible`]).
    pub fn with_invisible(mut self, invisible: bool) -> Self {
        self.invisible = invisible;
        self
    }

    /// Wrap the last generated line's expression in `invisible(...)` when the
    /// builder is marked invisible. Every tail ends with the expression the
    /// wrapper returns, so this is the single place visibility is applied.
    fn apply_visibility(&self, mut lines: Vec<String>) -> Vec<String> {
        if self.invisible
            && let Some(last) = lines.last_mut()
        {
            let expr = last.trim_start();
            let indent = &last[..last.len() - expr.len()];
            *last = format!("{indent}invisible({expr})");
        }
        lines
    }

    /// Inline-expression counterpart of [`Self::apply_visibility`].
    fn apply_visibility_expr(&self, expr: String) -> String {
        if self.invisible {
            format!("invisible({expr})")
        } else {
            expr
        }
    }

    /// Set the return strategy.
    pub fn with_strategy(mut self, strategy: ReturnStrategy) -> Self {
        self.strategy = strategy;
        self
    }

    /// Set the class name (for Self returns).
    pub fn with_class_name(mut self, class_name: String) -> Self {
        self.class_name = Some(class_name);
        self
    }

    /// Set the return class name (for cross-class ExternalPtr returns).
    pub fn with_return_class(mut self, return_class: String) -> Self {
        self.return_class = Some(return_class);
        self
    }

    /// Attach the method's cross-class return name when this builder uses
    /// [`ReturnStrategy::ReturnOtherClass`] or
    /// [`ReturnStrategy::ReturnOtherClassList`].
    ///
    /// `self_rust_type` is the enclosing impl block's own Rust type name
    /// (`type_ident.to_string()`) — every class-system generator already has
    /// `parsed_impl.type_ident` in scope alongside `class_name`, so this
    /// threads it through rather than widening `ParsedMethod` to carry it
    /// (#1375). It's consulted only for the `Vec<Self>` case
    /// ([`ParsedMethod::returns_self_list`]), where it stands in for the
    /// missing element name: the write-time resolver keys off the Rust type
    /// name (`ClassNameEntry::rust_type`), which is *not* necessarily the same
    /// string as this builder's `class_name` field —
    /// `#[miniextendr(class = "Override")]` makes the R-facing class name and
    /// the Rust struct name diverge, and `class_name` here is the former.
    pub fn with_return_class_from_method(
        mut self,
        method: &ParsedMethod,
        self_rust_type: &str,
    ) -> Self {
        if let Some(wrap) = &method.return_wrap {
            return self.with_explicit_wrap(wrap.clone());
        }
        self.nullable = method.returns_option();
        match self.strategy {
            ReturnStrategy::ReturnOtherClass => {
                let return_class = method
                    .returns_other_class()
                    .expect("return_class required for ReturnOtherClass strategy");
                self = self.with_return_class(return_class.to_string());
            }
            ReturnStrategy::ReturnOtherClassList => {
                let return_class = match method.returns_other_class_list() {
                    Some(ident) => ident.to_string(),
                    None => {
                        assert!(
                            method.returns_self_list(),
                            "return_class required for ReturnOtherClassList strategy"
                        );
                        self_rust_type.to_string()
                    }
                };
                self = self.with_return_class(return_class);
            }
            _ => {}
        }
        self
    }

    /// Mark `.val` as `NULL` for `None` (an `Option` return; see `nullable`).
    /// [`with_return_class_from_method`](Self::with_return_class_from_method)
    /// sets it for inherent methods.
    pub fn with_nullable(mut self, nullable: bool) -> Self {
        self.nullable = nullable;
        self
    }

    /// Select an explicit class constructor from a marker or wrap attribute.
    pub fn with_explicit_wrap(mut self, wrap: crate::return_wrap::ReturnWrap) -> Self {
        self.explicit_wrap = Some(wrap);
        self
    }

    /// Set the variable name to return for chaining (default: "self").
    pub fn with_chain_var(mut self, var: String) -> Self {
        self.chain_var = Some(var);
        self
    }

    /// Set indentation level (number of spaces).
    pub fn with_indent(mut self, indent: usize) -> Self {
        self.indent = indent;
        self
    }

    fn return_other_class_expr(&self) -> String {
        let return_class = self
            .return_class
            .as_ref()
            .expect("return_class required for ReturnOtherClass strategy");
        self.null_passes(format!(".__MX_WRAP_RETURN_{return_class}__(.val)"))
    }

    /// Pass a `NULL` `.val` (an `Option` method's `None`) through the
    /// cross-class wrap `expr`: no constructor takes `NULL`, and `lapply()`
    /// would turn it into `list()`.
    fn null_passes(&self, expr: String) -> String {
        if self.nullable {
            format!("if (is.null(.val)) NULL else {expr}")
        } else {
            expr
        }
    }

    /// List-shaped sibling of
    /// [`return_other_class_expr`](Self::return_other_class_expr) (#1284).
    ///
    /// The `LIST_` infix keeps the marker family disjoint from the scalar
    /// `.__MX_WRAP_RETURN_` prefix: the scalar resolver rewrites unrecognized
    /// markers of its own prefix to the bare expression, so a shared prefix
    /// would destroy list markers before the list resolver saw them.
    fn return_other_class_list_expr(&self) -> String {
        let return_class = self
            .return_class
            .as_ref()
            .expect("return_class required for ReturnOtherClassList strategy");
        self.null_passes(format!(".__MX_WRAP_LIST_RETURN_{return_class}__(.val)"))
    }

    // region: Core shared build path

    /// Emit:
    /// ```text
    /// <indent>.val <- <call_expr>
    /// <indent>if (inherits(.val, ...) ...) return(...)
    /// <tail lines — .val is live>
    /// ```
    ///
    /// All paths capture the `.Call()` result, dispatch on the tagged
    /// condition value if present, and then run the class-specific tail.
    fn build_with_tails(&self, tails: ReturnTails<'_>) -> Vec<String> {
        let indent = " ".repeat(self.indent);
        let class_name = self.class_name.as_deref().unwrap_or("");
        let call_expr = &self.call_expr;

        let mut lines = vec![format!("{}.val <- {}", indent, call_expr)];
        lines.extend(condition_check_lines_with_default(
            &indent,
            &self.raise_default,
        ));
        if let Some(wrap) = &self.explicit_wrap {
            lines.push(format!(
                "{indent}{}",
                wrap.r_expression(".val", self.class_name.as_deref())
            ));
            return self.apply_visibility(lines);
        }
        // An `Option<Self>` / `Option<&mut Self>` return's `None` is `NULL`;
        // neither the class wrap nor the receiver stands in for it.
        if self.nullable
            && matches!(
                self.strategy,
                ReturnStrategy::ReturnSelf | ReturnStrategy::ChainableMutation
            )
        {
            lines.push(format!("{indent}if (is.null(.val)) return(NULL)"));
        }
        match self.strategy {
            ReturnStrategy::ReturnSelf => {
                lines.extend((tails.self_tail)(&indent, class_name));
            }
            ReturnStrategy::ChainableMutation => {
                lines.extend((tails.chain_tail)(&indent));
            }
            ReturnStrategy::ReturnOtherClass => {
                lines.push(format!("{}{}", indent, self.return_other_class_expr()));
            }
            ReturnStrategy::ReturnOtherClassList => {
                lines.push(format!("{}{}", indent, self.return_other_class_list_expr()));
            }
            ReturnStrategy::Direct => {
                lines.extend((tails.direct_tail)(&indent));
            }
        }
        self.apply_visibility(lines)
    }

    // endregion

    /// Build R code lines for the method body.
    ///
    /// Returns a vector of strings, one per line (without trailing newlines).
    pub fn build(&self) -> Vec<String> {
        let chain_var = self.chain_var.as_deref().unwrap_or("self").to_owned();
        self.build_with_tails(ReturnTails {
            self_tail: Box::new(|indent, class_name| {
                assert!(
                    !class_name.is_empty(),
                    "class_name required for ReturnSelf strategy"
                );
                vec![
                    format!("{}class(.val) <- \"{}\"", indent, class_name),
                    format!("{}.val", indent),
                ]
            }),
            chain_tail: Box::new(move |indent| vec![format!("{}{}", indent, chain_var)]),
            direct_tail: Box::new(|indent| vec![format!("{}.val", indent)]),
        })
    }
}

/// Specialized builders for different class systems.
impl MethodReturnBuilder {
    /// Build R6-style return (chains via `self`; `invisible(self)` only when
    /// the method is marked invisible, #1213).
    pub fn build_r6_body(&self) -> Vec<String> {
        self.build_with_tails(ReturnTails {
            self_tail: Box::new(|indent, class_name| {
                assert!(
                    !class_name.is_empty(),
                    "class_name required for ReturnSelf strategy"
                );
                vec![format!("{}{}$new(.ptr = .val)", indent, class_name)]
            }),
            chain_tail: Box::new(|indent| vec![format!("{}self", indent)]),
            direct_tail: Box::new(|indent| vec![format!("{}.val", indent)]),
        })
    }

    /// Build S3-style return (uses structure() for Self returns).
    pub fn build_s3_body(&self) -> Vec<String> {
        let chain_var = self.chain_var.as_deref().unwrap_or("x").to_owned();
        self.build_with_tails(ReturnTails {
            self_tail: Box::new(|indent, class_name| {
                assert!(
                    !class_name.is_empty(),
                    "class_name required for ReturnSelf strategy"
                );
                vec![format!(
                    "{}structure(.val, class = \"{}\")",
                    indent, class_name
                )]
            }),
            chain_tail: Box::new(move |indent| vec![format!("{}{}", indent, chain_var)]),
            direct_tail: Box::new(|indent| vec![format!("{}.val", indent)]),
        })
    }

    /// Build S7-style method body lines (creates new S7 object with .ptr).
    ///
    /// Returns lines suitable for embedding inside an outer `function(...) { ... }`
    /// block — unlike [`build_s7_inline`](Self::build_s7_inline) which wraps the
    /// body in its own `{ }` and is intended for callers that emit
    /// `function(...) <expr>` directly (e.g., S7 `convert` definitions).
    pub fn build_s7_body(&self) -> Vec<String> {
        // The chained-mutation tail returns the receiver. The S7 generic method
        // names its receiver `x`; the per-class fast-path shortcut (#949) names
        // it `self`. Honour `chain_var` (default `x`) so both reuse this body.
        let chain_var = self.chain_var.as_deref().unwrap_or("x").to_owned();
        self.build_with_tails(ReturnTails {
            self_tail: Box::new(|indent, class_name| {
                assert!(
                    !class_name.is_empty(),
                    "class_name required for ReturnSelf strategy"
                );
                vec![format!("{}{}(.ptr = .val)", indent, class_name)]
            }),
            chain_tail: Box::new(move |indent| vec![format!("{}{}", indent, chain_var)]),
            direct_tail: Box::new(|indent| vec![format!("{}.val", indent)]),
        })
    }

    /// Build S4-style method body lines (uses methods::new() to wrap Self returns).
    ///
    /// Returns lines suitable for embedding inside an outer
    /// `function(...) { ... }` block, mirroring [`build_s7_body`](Self::build_s7_body).
    pub fn build_s4_body(&self) -> Vec<String> {
        let chain_var = self.chain_var.as_deref().unwrap_or("x");
        self.build_with_tails(ReturnTails {
            self_tail: Box::new(|indent, class_name| {
                assert!(
                    !class_name.is_empty(),
                    "class_name required for ReturnSelf strategy"
                );
                vec![format!(
                    "{}methods::new(\"{}\", ptr = .val)",
                    indent, class_name
                )]
            }),
            chain_tail: Box::new(|indent| vec![format!("{indent}{chain_var}")]),
            direct_tail: Box::new(|indent| vec![format!("{}.val", indent)]),
        })
    }

    /// Build S7-style return (creates new S7 object with .ptr).
    ///
    /// Returns a multi-line block expression that performs the condition check
    /// inline (suitable for S7 property definitions / convert methods that
    /// require a single expression).
    pub fn build_s7_inline(&self) -> String {
        let inner = if let Some(wrap) = &self.explicit_wrap {
            wrap.r_expression(".val", self.class_name.as_deref())
        } else {
            match self.strategy {
                ReturnStrategy::ReturnSelf => {
                    let class_name = self
                        .class_name
                        .as_ref()
                        .expect("class_name required for ReturnSelf strategy");
                    self.null_passes(format!("{}(.ptr = .val)", class_name))
                }
                ReturnStrategy::ChainableMutation => self.null_passes("x".to_string()),
                ReturnStrategy::ReturnOtherClass => self.return_other_class_expr(),
                ReturnStrategy::ReturnOtherClassList => self.return_other_class_list_expr(),
                ReturnStrategy::Direct => ".val".to_string(),
            }
        };
        let inner = self.apply_visibility_expr(inner);
        condition_check_inline_block(&self.call_expr, &inner, "    ")
    }

    /// Build S4-style return (uses methods::new()).
    ///
    /// Returns a multi-line block expression that performs the condition check
    /// inline.
    pub fn build_s4_inline(&self) -> String {
        let inner = if let Some(wrap) = &self.explicit_wrap {
            wrap.r_expression(".val", self.class_name.as_deref())
        } else {
            match self.strategy {
                ReturnStrategy::ReturnSelf => {
                    let class_name = self
                        .class_name
                        .as_ref()
                        .expect("class_name required for ReturnSelf strategy");
                    self.null_passes(format!("methods::new(\"{}\", ptr = .val)", class_name))
                }
                ReturnStrategy::ChainableMutation => self.null_passes("x".to_string()),
                ReturnStrategy::ReturnOtherClass => self.return_other_class_expr(),
                ReturnStrategy::ReturnOtherClassList => self.return_other_class_list_expr(),
                ReturnStrategy::Direct => ".val".to_string(),
            }
        };
        let inner = self.apply_visibility_expr(inner);
        condition_check_inline_block(&self.call_expr, &inner, "    ")
    }
}

#[cfg(test)]
mod tests;
// endregion