miniextendr_macros/miniextendr_impl/

env_class.rs

//! Env-class R wrapper generator.
//!
//! Generates an R environment (`new.env(parent = emptyenv())`) that serves as
//! the class namespace, with `obj$method()` dispatched through an `$.ClassName`
//! S3 method. This is the **fastest** of the six class systems and has **no R
//! package dependencies**, but provides no formal class machinery: no
//! inheritance, no multi-dispatch, no slot validation. Pick env for simple
//! ExternalPtr-backed APIs; reach for R6/S3/S4/S7 when you need dispatch or
//! formal class semantics.

use super::ParsedImpl;

/// Generates the R wrapper of an environment-based class, in the parts the
/// wrapper writer merges per type ([`super::ClassWrapper`], #1776).
///
/// Produces an R environment object (`new.env(parent = emptyenv())`) that serves as a
/// class namespace, with methods attached as `ClassName$method_name`. This pattern
/// supports both inherent methods and trait namespace dispatch via `$`/`[[`.
///
/// The generated code includes:
/// - Class environment: `ClassName <- new.env(parent = emptyenv())`
/// - Constructor: `ClassName$new(...)` that calls the Rust `new` function, sets
///   `class(self) <- "ClassName"`, and returns the ExternalPtr as `self`
/// - Instance methods: `ClassName$method(...)` whose bodies read a free `self`,
///   which `$` dispatch binds in a fresh environment over the method's own
/// - Static methods: `ClassName$method(...)` that call Rust directly
/// - `$.ClassName` S3 method: dispatches `obj$method(...)` by looking up the method
///   in the class environment, binding `.mx_self` for instance methods, and supporting
///   trait namespace environments (nested envs with `.__mx_instance__` attributes),
///   through the package's shared `.miniextendr_env_method` helper
/// - `[[.ClassName`: the same lookup, with `exact` (ignored) and a `...` that
///   refuses every argument (#2174)
/// - With `env(r_data_accessors)`: a field branch at the top of `$.ClassName`
///   (a `#[r_data]` field wins over a method of the same name),
///   `.DollarNames.ClassName` (the fields, then the methods; #1885), and,
///   unless the getters-only `r_data_accessors = "get"`, `$<-.ClassName` with
///   its `[[<-.ClassName` alias (`field_syntax.rs`, #1848)
///
/// Roxygen2 documentation is generated for the class, each method, and the
/// dispatch methods, with appropriate `@export`/`@keywords internal`/`@noRd` tags.
///
/// The class environment and constructor are the head; the instance and
/// static methods are the members; the dispatch methods are the tail.
pub fn generate_env_class(parsed_impl: &ParsedImpl) -> super::ClassWrapper {
    use crate::r_class_formatter::{
        ClassDocBuilder, MethodDocBuilder, ParsedImplExt, should_export_from_tags,
    };

    let class_name = parsed_impl.class_name();
    let type_ident = &parsed_impl.type_ident;
    // Check if class has @noRd - if so, skip method documentation. A plain
    // `noexport` (without `internal`) is folded in too — it must suppress Rd
    // contribution entirely, matching `ClassDocBuilder::build`'s `suppress_rd` gate.
    let class_has_no_rd = crate::roxygen::has_roxygen_tag(&parsed_impl.doc_tags, "noRd")
        || (parsed_impl.noexport && !parsed_impl.internal);

    let mut w = super::ClassWrapper::default();
    let mut lines = Vec::new();

    // Class environment documentation and definition
    let class_docs = ClassDocBuilder::new(&class_name, type_ident, &parsed_impl.doc_tags, "")
        .with_export_control(parsed_impl.internal, parsed_impl.noexport);
    lines.extend(class_docs.build());
    w.class_docs = class_docs.docs();
    w.mark_class_doc_lines(&mut lines, parsed_impl);
    lines.push(format!("{} <- new.env(parent = emptyenv())", class_name));
    lines.push(String::new());

    // Constructor
    if let Some(ctx) = parsed_impl.constructor_context() {
        w.member_names.push(format!("`{class_name}$new`"));
        lines.push(ctx.source_comment(type_ident));
        // Skip method documentation if class has @noRd
        if !class_has_no_rd {
            let choice_docs = ctx.choice_param_docs();
            let method_doc =
                MethodDocBuilder::new(&class_name, "new", type_ident, &ctx.method.doc_tags)
                    .with_source_method(&ctx.method.ident)
                    .with_name_prefix("$")
                    .with_params_as_details()
                    .with_r_params(&ctx.params)
                    .with_choice_param_docs(&choice_docs);
            lines.extend(method_doc.build());
        }
        lines.push(format!("{}$new <- function({}) {{", class_name, ctx.params));
        for check in ctx.precondition_checks() {
            lines.push(format!("  {}", check));
        }
        // Inject match.arg validation for match_arg/choices params
        for line in ctx.match_arg_prelude() {
            lines.push(format!("  {}", line));
        }
        lines.push(format!("  .val <- {}", ctx.static_call()));
        lines.extend(crate::method_return_builder::condition_check_lines("  "));
        lines.push("  self <- .val".to_string());
        lines.push(format!("  class(self) <- \"{}\"", class_name));
        lines.push("  self".to_string());
        lines.push("}".to_string());
        lines.push(String::new());
    }
    w.head = std::mem::take(&mut lines);

    // Instance methods
    for ctx in parsed_impl.instance_method_contexts() {
        let method_name = ctx.method.r_method_name();
        w.member_names.push(format!("`{class_name}${method_name}`"));
        lines.push(ctx.source_comment(type_ident));
        // Skip method documentation if class has @noRd
        if !class_has_no_rd {
            let choice_docs = ctx.choice_param_docs();
            let method_doc =
                MethodDocBuilder::new(&class_name, &method_name, type_ident, &ctx.method.doc_tags)
                    .with_source_method(&ctx.method.ident)
                    .with_name_prefix("$")
                    .with_params_as_details()
                    .with_r_params(&ctx.params)
                    .with_choice_param_docs(&choice_docs);
            lines.extend(method_doc.build());
        }

        // `$` takes an R symbol: quote operator names (#1475).
        lines.push(format!(
            "{}${} <- function({}) {{",
            class_name,
            crate::naming::r_def_name(&method_name),
            ctx.params
        ));

        let what = format!("{}${}", class_name, method_name);
        ctx.emit_method_prelude(&mut lines, "  ", &what, &ctx.params);

        let call = ctx.instance_call(".mx_self");
        let strategy = crate::ReturnStrategy::for_method(ctx.method);
        let return_builder = crate::MethodReturnBuilder::new(call)
            .with_strategy(strategy)
            .with_invisible(ctx.method.is_invisible())
            .with_chain_var(".mx_self".to_string())
            .with_class_name(class_name.clone())
            .with_return_class_from_method(ctx.method, &type_ident.to_string());
        lines.extend(return_builder.build());

        lines.push("}".to_string());
        lines.push(String::new());
    }

    // Static methods
    for ctx in parsed_impl.static_method_contexts() {
        let method_name = ctx.method.r_method_name();
        w.member_names.push(format!("`{class_name}${method_name}`"));
        lines.push(ctx.source_comment(type_ident));
        // Skip method documentation if class has @noRd
        if !class_has_no_rd {
            let choice_docs = ctx.choice_param_docs();
            // The constructor's arguments are details of `$new`; its alias
            // doesn't repeat them.
            let doc_tags = parsed_impl.static_doc_tags(
                ctx.method,
                &format!("{class_name}${method_name}()"),
                &format!("{class_name}$new()"),
                false,
            );
            let method_doc =
                MethodDocBuilder::new(&class_name, &method_name, type_ident, &doc_tags)
                    .with_source_method(&ctx.method.ident)
                    .with_name_prefix("$")
                    .with_params_as_details()
                    .with_r_params(&ctx.params)
                    .with_choice_param_docs(&choice_docs);
            lines.extend(method_doc.build());
        }

        lines.push(format!(
            "{}${} <- function({}) {{",
            class_name,
            crate::naming::r_def_name(&method_name),
            ctx.params
        ));

        let what = format!("{}${}", class_name, method_name);
        ctx.emit_method_prelude(&mut lines, "  ", &what, &ctx.params);

        let strategy = crate::ReturnStrategy::for_method(ctx.method);
        let return_builder = crate::MethodReturnBuilder::new(ctx.static_call())
            .with_strategy(strategy)
            .with_invisible(ctx.method.is_invisible())
            .with_class_name(class_name.clone())
            .with_return_class_from_method(ctx.method, &type_ident.to_string());
        lines.extend(return_builder.build());

        lines.push("}".to_string());
        lines.push(String::new());
    }
    w.members = std::mem::take(&mut lines);

    // $ dispatch - export as S3 methods
    // Handles both functions (inherent methods) and environments (trait namespaces)
    let should_export = should_export_from_tags(
        &parsed_impl.doc_tags,
        parsed_impl.noexport || parsed_impl.internal,
    );

    // Generate roxygen tags for dispatch methods.
    // roxygen2 8.0.0+ enforces that any `generic.class`-named function carry
    // @export or @exportS3Method (@noRd alone doesn't satisfy the check). We
    // always emit @export so roxygen2 emits a properly-quoted
    // `S3method("$", Class)` / `S3method("[[", Class)` (bare @exportS3Method
    // skips the operator-name quoting and produces invalid NAMESPACE entries).
    // For internal/noexport classes the @rdname target is dropped so the
    // helpers don't bleed into the user-visible Rd page.
    // `env(r_data_accessors)` (#1848): `$` / `[[` read a field before the
    // method lookup, and `$<-` / `[[<-` write one.
    let fields = parsed_impl.r_data_accessors.enabled();
    if fields {
        lines.push(format!(
            "# Field syntax for the `#[r_data]` fields of {type_ident} (`env(r_data_accessors)`)."
        ));
        lines.push(super::field_syntax::env_load_check(parsed_impl));
        lines.push(String::new());
    }
    if class_has_no_rd {
        lines.push("#' @noRd".to_string());
        lines.push("#' @export".to_string());
    } else if !should_export {
        lines.push("#' @export".to_string());
    } else {
        // The class's topic: the impl's own `@rdname`, else the class page.
        lines.extend(super::field_syntax::page_lines(
            parsed_impl,
            &[
                ("self", "The object instance."),
                (
                    "name",
                    if fields {
                        super::field_syntax::env_name_param(parsed_impl)
                    } else {
                        "Method name for dispatch."
                    },
                ),
            ],
        ));
        lines.push("#' @export".to_string());
    }
    // The lookup `$` and `[[` share. `[[` is its own function, not an alias
    // of `$`, so that each method's frame names its own generic for
    // `.miniextendr_frame_call`.
    let mut lookup = Vec::new();
    if fields {
        lookup.extend(super::field_syntax::env_field_branch(parsed_impl));
    }
    let method_lookup = format!(".miniextendr_env_method(self, name, {class_name})");
    if fields {
        lookup.push(format!("  obj <- {method_lookup}"));
        lookup.push("  if (is.null(obj)) {".to_string());
        lookup.extend(super::field_syntax::env_unknown_name_check(parsed_impl));
        lookup.push("  }".to_string());
        lookup.push("  obj".to_string());
    } else {
        lookup.push(format!("  {method_lookup}"));
    }
    lines.push(format!("`$.{}` <- function(self, name) {{", class_name));
    lines.extend(lookup.iter().cloned());
    lines.push("}".to_string());
    // `[[` takes `exact`, as a list's does, and ignores it: names match
    // exactly. Nothing reads its `...`, so every argument there is refused
    // (#2174).
    if class_has_no_rd {
        lines.push("#' @noRd".to_string());
        lines.push("#' @export".to_string());
    } else if !should_export {
        lines.push("#' @export".to_string());
    } else {
        lines.extend(super::field_syntax::page_lines(
            parsed_impl,
            &[
                ("...", "Refused: `[[` takes one name."),
                ("exact", "Ignored: names match exactly."),
            ],
        ));
        lines.push("#' @export".to_string());
    }
    lines.push(format!(
        "`[[.{class_name}` <- function({}) {{",
        super::field_syntax::ENV_SUBSET_FORMALS
    ));
    lines.push(super::field_syntax::env_subset_dots_check(parsed_impl));
    lines.extend(lookup);
    lines.push("}".to_string());
    if fields {
        lines.extend(super::field_syntax::env_dollar_names(
            parsed_impl,
            !class_has_no_rd && should_export,
        ));
    }
    if fields && parsed_impl.r_data_accessors.setters() {
        lines.extend(super::field_syntax::env_replacement_methods(
            parsed_impl,
            !class_has_no_rd && should_export,
        ));
    }

    w.tail = lines;
    w
}

/// The env class as one string: [`generate_env_class`], rendered.
#[cfg(test)]
pub fn generate_env_r_wrapper(parsed_impl: &ParsedImpl) -> String {
    generate_env_class(parsed_impl).render()
}