miniextendr_macros/

externalptr_derive.rs

//! # `#[derive(ExternalPtr)]` - ExternalPtr Support
//!
//! This module implements the `#[derive(ExternalPtr)]` macro which generates
//! a `TypedExternal` impl for use with `ExternalPtr<T>`.
//!
//! Trait ABI wrapper infrastructure is automatically generated when you use
//! `#[miniextendr]` on `impl Trait for Type` blocks.
//!
//! ## Sidecar codegen vs `#[miniextendr]` fns
//!
//! `#[derive(ExternalPtr)]` with `#[r_data]` fields emits a pair of C/R
//! wrappers per sidecar field (`<Type>_get_<field>` /
//! `<Type>_set_<field>`). **These wrappers do NOT go through
//! `c_wrapper_builder::CWrapperContext`** — they are hand-rolled in this
//! module so they can present the simplest signature R expects from a slot
//! accessor:
//!
//! | Aspect | `#[miniextendr]` fn / method (`c_wrapper_builder`) | Sidecar accessor (here) |
//! |---|---|---|
//! | First C param | `__miniextendr_call: SEXP` | none |
//! | Last C param | — | `require_live: SEXP`, the restored-pointer flag (#1891) |
//! | C `numArgs` | 1 + user args | `2` (getter) / `3` (setter) |
//! | R `.Call` | `.Call(C_…, .call = sys.call(), …)` | `.Call(C_…, x, FALSE)` / `.Call(C_…, x, value, FALSE)`; the field methods pass `TRUE` |
//! | Error transport | tagged-condition SEXP via `with_r_unwind_protect(…, Some(call))` | tagged-condition SEXP via `with_r_unwind_protect(…, None)`; the R guard's `sys.call()` supplies attribution |
//!
//! **A sidecar R wrapper passes no `.call` argument.** The C function doesn't
//! have a slot for it: R would throw "Incorrect number of arguments" at
//! runtime (#344, #348).
//!
//! **The `require_live` flag** is how the generated `$` / `[[` / `$<-` /
//! `[[<-` field methods refuse a pointer restored from a saved session while
//! the standalone accessors, the R6 active bindings and the S7 properties
//! keep reading its `Sidecar` values (#1891): one accessor per field, no
//! extra `.Call()`. Only a `Sidecar` slot's accessors read the flag
//! (`externalptr::sidecar_require_live`); the other kinds need the live Rust
//! value whatever it says.
//!
//! ## Usage
//!
//! ### Basic (no traits)
//!
//! ```ignore
//! #[derive(ExternalPtr)]
//! struct MyData {
//!     value: i32,
//! }
//! // Generates: impl TypedExternal for MyData { ... }
//! ```
//!
//! ### With R Sidecar Slots and Class System
//!
//! The `#[r_data]` attribute marks fields that get R accessors. Every public
//! slot gets the standalone `Type_get_field(x)` / `Type_set_field(x, value)`,
//! which take the pointer or any object carrying it in `.ptr` (a list, an
//! environment, an R6 / S4 / S7 handle). `#[externalptr(...)]` names the class
//! system; the impl's `r_data_accessors` option also wires the slots into the
//! class. Under the S3, S4 and env field syntax, `$` / `[[` are the class's R
//! API and the standalone accessors are internal: no `@export`, no "Type
//! Sidecar Accessors" page (#1900). The derive emits both renderings in a
//! `SidecarAccessorsEntry`; the wrapper writer picks one by the class's
//! `ClassNameEntry::field_syntax`, since the impl block is a separate
//! expansion. Otherwise they are exported on the type's page.
//!
//! | Class System | Attribute | R Accessors |
//! |--------------|-----------|-------------|
//! | Environment | `#[externalptr(env)]` (default) + `#[miniextendr(env(r_data_accessors))]` | `obj$field` / `obj[["field"]]` next to the methods, `obj$field <- value` |
//! | R6 | `#[externalptr(r6)]` + `#[miniextendr(r6(r_data_accessors))]` | Active bindings, `obj$field` / `obj$field <- value` |
//! | S3 | `#[externalptr(s3)]` + `#[miniextendr(s3(r_data_accessors))]` | `$` / `[[` / `$<-` / `[[<-` methods |
//! | S4 | `#[externalptr(s4)]` + `#[miniextendr(s4(r_data_accessors))]` | `$` / `$<-` methods |
//! | S7 | `#[externalptr(s7)]` + `#[miniextendr(s7(r_data_accessors))]` | Properties, `obj@field` / `obj@field <- value` |
//!
//! For S3, S4 and env, `r_data_accessors = "get"` generates the getters only.
//! The `$` / `[[` methods share the helpers [`generate_field_syntax_helpers`]
//! prepares for every type with R accessors (#1848). The wrapper writer includes
//! them only when an impl enables S3, S4 or env field syntax.
//!
//! Standalone setters and R6 active-binding setters return the receiver invisibly
//! by default. `#[r_data(setter = "visible")]` exposes that return value;
//! `setter = "invisible"` explicitly requests the default. These options also
//! control S7 property setters, whose unmarked return remains visible.
//! R assignment itself stays invisible regardless of the setter's choice.
//!
//! Four field tiers are supported:
//!
//! 1. **Rooted values** (`Sidecar<T>`) - kept in the external pointer's
//!    protection list, which roots them and serializes them with the
//!    pointer. The derive generates typed accessors as associated functions
//!    of the struct, with the field's visibility, taking a view or the
//!    `ExternalPtr` handle (the struct holds nothing that points back at its
//!    pointer): `#[r_data(ref)]` a getter
//!    `fn f(ptr: &impl SidecarOwner<Self>) -> T`, `#[r_data(mut)]` a setter
//!    `fn set_f(ptr: &mut impl SidecarOwnerMut<Self>, value: T)`,
//!    `#[r_data(ref, mut)]` or a bare `#[r_data]` both. A method that needs
//!    the values takes a view as its receiver (`self: ExternalPtrRef<'_, Self>`
//!    / `mut self: ExternalPtrMut<'_, Self>`) and calls `Self::f(&self)`; see
//!    `miniextendr_api::externalptr::Sidecar`. A bare `SEXP` field is
//!    refused: the struct can't root it.
//! 2. **Scalars** (`i32`, `f64`, `bool`, `u8`) - struct fields, returned as a
//!    length-1 vector and written with `Rf_as*`
//! 3. **Conversion types** (anything else) - struct fields, converted with the
//!    `IntoR`/`TryFromSexp` traits on every read and write
//! 4. **Computed fields** (`#[r_data(get = "Self::f")] pub f: Computed`,
//!    #1883) - no value in the struct; the getter calls the named
//!    `fn(&Self) -> impl IntoR` on the live Rust value. There is no setter:
//!    no `Type_set_f()`, and under the get/set field syntax an assignment
//!    raises `miniextendr_read_only_field`. Only `pub`, and not under
//!    `#[externalptr(r6)]` / `#[externalptr(s7)]`, whose bindings and
//!    properties need a setter (#1888).
//!
//! `#[r_data(name = "keys")]` gives a field its R name (#1891): the field
//! list, the `$` / `[[` labels, the R6 binding / S7 property and the
//! standalone `Type_get_keys()` / `Type_set_keys()` use it; the C symbols and
//! the Rust accessors keep the Rust identifier. The name must be a syntactic
//! R name, unique in the type, and not `.ptr`. A `Sidecar` field's R name is
//! also the save format (#2215): a save names the field's slot after it
//! (`SIDECAR_NAMES`), and a reload or a rebuild hook finds the slot by it. So
//! renaming the Rust field keeps earlier saves readable (give it the old
//! ident as its `name` if it had none), while renaming the R name orphans
//! the slot in every earlier save.
//!
//! Scalar, conversion and computed values come from the Rust struct, behind
//! the pointer's address, which `saveRDS` does not write. The R accessors of
//! a `Sidecar` field read and write the protection list by slot index (a
//! restored pointer's by the field's R name, #2187): the
//! setter validates the value with `TryFromSexp::<T>` and stores the value R
//! gave, and the standalone accessors keep working on a pointer `readRDS()`
//! brought back without an address (checked by the type ID in `prot[0]`).
//!
//! ### A saved and restored object
//!
//! `saveRDS()` / `serialize()` keep the pointer's `prot` list (the `Sidecar`
//! values and the user slot) but not the Rust value. On the restored pointer
//! the standalone `Sidecar` accessors, the R6 active bindings and the S7
//! properties work; the generated `$` / `[[` / `$<-` / `[[<-` field methods
//! refuse it whatever the field (they pass the accessors' `require_live`
//! flag, #1891), and the accessor of a struct or computed field, like every
//! method, raises the classed error `miniextendr_restored_no_value` ("restored
//! from a saved session and has no Rust value; re-create it"). A pointer
//! another version of the crate saved is refused by every accessor with
//! `miniextendr_restored_other_version`, which names both versions.
//! `#[externalptr(restored(class = ["pkg_saved", "pkg_error"], message =
//! "..."))]` puts the package's classes in front of those (which stay) and
//! replaces the message, on every restored refusal of the type. Its
//! `refuse = "every_read"` (#1901) extends the field methods' refusal to the
//! reads that never call an accessor: `names()` and an unknown `$` / `[[`
//! name check the pointer first through one more C function
//! (`.rdata_live_<Type>`, `externalptr::sidecar_r_live`), and `.DollarNames()`
//! returns `character(0)` for a restored pointer. R's `y <- x`
//! shares the one Rust value and the one `prot` list: a write through `y` is
//! visible through `x`.
//!
//! `#[externalptr(field_error(class = ["pkg_error_field", "pkg_error"]))]`
//! (#1899) puts the package's classes in front of the field readers' own
//! errors: a position that picks no field (`subscriptOutOfBoundsError`
//! stays behind them, and `0` / a negative position raise it too), a pointer
//! of another type, and a receiver of the class that carries no pointer
//! (`miniextendr_no_handle`, which also gets the `restored(class)` classes).
//! They reach R as `.rdata_error_class_<Type>` and Rust as
//! `TypedExternal::FIELD_ERROR_CLASS`. `field_error(no_field_hint = "...")`
//! (#2112) adds the package's sentence after the field list of the
//! `miniextendr_no_field` error, each `%s` in it the name asked for.
//!
//! ```ignore
//! #[derive(ExternalPtr)]
//! #[externalptr(r6)]
//! pub struct MyType {
//!     pub x: i32,
//!
//!     #[r_data]
//!     r: RSidecar,  // Selector - enables R accessors for this type
//!
//!     #[r_data(ref, mut)]
//!     pub keys: Sidecar<Vec<i32>>,  // In the protection list; `MyType::keys(&ptr)` / `MyType::set_keys(&mut ptr, v)`
//!
//!     #[r_data]
//!     pub count: i32,  // Scalar struct field
//!
//!     #[r_data]
//!     pub name: String,  // Conversion: uses IntoR/TryFromSexp
//! }
//!
//! #[miniextendr(r6(r_data_accessors))]
//! impl MyType {
//!     pub fn new(n: i32) -> Self {
//!         MyType { x: 0, r: RSidecar, keys: Sidecar::new((1..=n).collect()), count: n, name: String::new() }
//!     }
//!     pub fn key_count(self: ExternalPtrRef<'_, Self>) -> usize {
//!         Self::keys(&self).len()
//!     }
//! }
//! // Generates: active bindings `keys`, `count`, `name` in the R6Class
//! ```
//!
//! ### Trait ABI wiring
//!
//! ```ignore
//! #[derive(ExternalPtr)]
//! struct MyCounter {
//!     value: i32,
//! }
//!
//! #[miniextendr]
//! impl Counter for MyCounter { /* ... */ }
//! ```
//!
//! ## Generated Types
//!
//! The runtime's generic `ErasedObject<MyCounter>` owns the value and its
//! `mx_erased` header; no per-type wrapper struct or drop function is emitted.
//!
//! ### Base Vtable
//!
//! ```ignore
//! static __MX_BASE_VTABLE_MyCounter: mx_base_vtable = mx_base_vtable {
//!     drop: ErasedObject::<MyCounter>::drop_raw,
//!     concrete_tag: __MX_TAG_MyCounter,
//!     query: ErasedObject::<MyCounter>::query,
//!     data_offset: ErasedObject::<MyCounter>::DATA_OFFSET,
//! };
//! ```
//!
//! Trait implementations register their vtables with the dispatch registry.
//! The shared `registry::universal_query` looks them up by concrete type tag
//! and trait tag; the derive emits no per-type query function.

use proc_macro2::{Span, TokenStream};
use syn::{DeriveInput, Field, Ident, Visibility};

use crate::miniextendr_impl::ClassSystem;

/// The package's condition classes and message for a pointer of the type
/// restored from a saved session, `#[externalptr(restored(class = "..." |
/// ["...", "..."], message = "...", refuse = "every_read"))]` (#1891,
/// #1901). Each is optional; the derive emits
/// `TypedExternal::RESTORED_ERROR_CLASS` / `RESTORED_ERROR_MESSAGE` for the
/// ones given.
#[derive(Debug, Default, Clone, PartialEq, Eq)]
struct RestoredOptions {
    /// The classes, in order, put in front of the `miniextendr_restored*`
    /// classes.
    class: Vec<String>,
    /// The message, replacing miniextendr's in both restored cases.
    message: Option<String>,
    /// `refuse = "every_read"`: the field methods refuse a restored pointer
    /// on the reads that never reach a field accessor too (`names()`, a name
    /// that is not a field), and `.DollarNames()` offers nothing for it
    /// (#1901). The derive emits the liveness check they call.
    every_read: bool,
}

/// What `#[externalptr(...)]` says about the type.
struct ExternalPtrAttrs {
    class_system: ClassSystem,
    restored: RestoredOptions,
    /// `field_error(class = ..., message = ...)`: the field readers' own
    /// errors (#1899, #1920).
    field_error: FieldErrorOptions,
    /// `rebuild = path`: the hook that rebuilds a pointer restored from a
    /// saved session (#2146).
    rebuild: Option<syn::Path>,
    /// `any_version`, next to `rebuild`: the hook also rebuilds a save by
    /// another version of the crate (#2187).
    any_version: bool,
}

/// `#[externalptr(field_error(class = ..., message = ..., no_field_hint = ...))]`.
#[derive(Default)]
struct FieldErrorOptions {
    /// The classes put in front of the errors the R field readers raise
    /// themselves (#1899), `TypedExternal::FIELD_ERROR_CLASS`.
    class: Vec<String>,
    /// The package's message for a receiver of the class whose pointer is no
    /// `T` or that carries none (#1920), `TypedExternal::FIELD_ERROR_MESSAGE`.
    message: Option<String>,
    /// A sentence the `miniextendr_no_field` error adds after its field list,
    /// each `%s` replaced by the name asked for (#2112).
    no_field_hint: Option<String>,
}

/// Parse `#[externalptr(...)]` attributes: the class system, the restored
/// refusal's classes, message and scope, and the field readers' classes.
///
/// Supported forms:
/// - `#[externalptr(env)]` - Environment style (default)
/// - `#[externalptr(r6)]` - R6 class
/// - `#[externalptr(s3)]` - S3 class
/// - `#[externalptr(s4)]` - S4 class
/// - `#[externalptr(s7)]` - S7 class
/// - `#[externalptr(vctrs)]` - vctrs class
/// - `#[externalptr(restored(class = "pkg_saved", message = "...", refuse = "every_read"))]`,
///   with `class = ["pkg_saved", "pkg_error"]` for several classes; next to
///   the class system (`#[externalptr(s3, restored(...))]`) or on its own.
/// - `#[externalptr(field_error(class = ["pkg_error_config", "pkg_error"], message = "...", no_field_hint = "..."))]`
/// - `#[externalptr(rebuild = Self::from_saved)]`, the rebuild hook of a
///   pointer restored from a saved session (#2146), with `any_version` for
///   saves by another version of the crate too (#2187).
fn parse_externalptr_attrs(input: &DeriveInput) -> syn::Result<ExternalPtrAttrs> {
    let mut class_system = ClassSystem::Env; // Default
    let mut restored: Option<RestoredOptions> = None;
    let mut field_error: Option<FieldErrorOptions> = None;
    let mut rebuild: Option<syn::Path> = None;
    let mut any_version: Option<proc_macro2::Span> = None;

    for attr in &input.attrs {
        if attr.path().is_ident("externalptr") {
            attr.parse_nested_meta(|meta| {
                let ident_str = meta
                    .path
                    .get_ident()
                    .map(|i| i.to_string())
                    .unwrap_or_default();

                match ident_str.as_str() {
                    "env" => class_system = ClassSystem::Env,
                    "r6" => class_system = ClassSystem::R6,
                    "s3" => class_system = ClassSystem::S3,
                    "s4" => class_system = ClassSystem::S4,
                    "s7" => class_system = ClassSystem::S7,
                    "vctrs" => class_system = ClassSystem::Vctrs,
                    "restored" => {
                        if restored.is_some() {
                            return Err(meta.error("`restored(...)` is given twice"));
                        }
                        restored = Some(parse_restored_options(&meta)?);
                    }
                    "field_error" => {
                        if field_error.is_some() {
                            return Err(meta.error("`field_error(...)` is given twice"));
                        }
                        field_error = Some(parse_field_error_options(&meta)?);
                    }
                    "rebuild" => {
                        if rebuild.is_some() {
                            return Err(meta.error("`rebuild = ...` is given twice"));
                        }
                        rebuild = Some(meta.value()?.parse::<syn::Path>().map_err(|e| {
                            syn::Error::new(
                                e.span(),
                                "`rebuild` takes the path of a function `fn(&Saved<'_, Self>) -> Result<Self, E>`, e.g. `rebuild = Self::from_saved`",
                            )
                        })?);
                    }
                    "any_version" => {
                        if any_version.is_some() {
                            return Err(meta.error("`any_version` is given twice"));
                        }
                        any_version = Some(syn::spanned::Spanned::span(&meta.path));
                    }
                    _ => {
                        return Err(syn::Error::new_spanned(
                            &meta.path,
                            format!(
                                "unknown `externalptr` option '{}'; expected a class system (env, r6, s3, s4, s7, vctrs), `restored(class = ..., message = ..., refuse = ...)`, `field_error(class = ..., message = ...)`, `rebuild = path` or `any_version`",
                                ident_str
                            ),
                        ));
                    }
                }
                Ok(())
            })?;
        }
    }

    if let (Some(span), None) = (any_version, &rebuild) {
        return Err(syn::Error::new(
            span,
            "`any_version` lets the rebuild hook read a save by another version of the crate; \
             it needs `rebuild = path` next to it",
        ));
    }

    Ok(ExternalPtrAttrs {
        class_system,
        restored: restored.unwrap_or_default(),
        field_error: field_error.unwrap_or_default(),
        rebuild,
        any_version: any_version.is_some(),
    })
}

/// The value of a `class = "..."` or `class = ["...", ...]` argument: the
/// condition classes in order, non-empty, none of them empty.
fn parse_class_list(inner: &syn::meta::ParseNestedMeta) -> syn::Result<Vec<String>> {
    let value = inner.value()?;
    let classes: Vec<syn::LitStr> = if value.peek(syn::token::Bracket) {
        let content;
        syn::bracketed!(content in value);
        content
            .parse_terminated(<syn::LitStr as syn::parse::Parse>::parse, syn::Token![,])?
            .into_iter()
            .collect()
    } else {
        vec![value.parse()?]
    };
    if classes.is_empty() {
        return Err(inner.error("`class` needs at least one condition class"));
    }
    for class in &classes {
        if class.value().is_empty() {
            return Err(syn::Error::new_spanned(
                class,
                "a condition class can't be empty",
            ));
        }
    }
    Ok(classes.iter().map(syn::LitStr::value).collect())
}

/// The arguments of `restored(...)`: `class = "..."` or `class = ["...", ...]`
/// (non-empty, in order), `message = "..."` (non-empty) and `refuse =
/// "every_read"`, each at most once. syn refuses empty parentheses, so at
/// least one is given.
fn parse_restored_options(meta: &syn::meta::ParseNestedMeta) -> syn::Result<RestoredOptions> {
    let mut options = RestoredOptions::default();
    let mut class_given = false;
    let mut refuse_given = false;
    meta.parse_nested_meta(|inner| {
        if inner.path.is_ident("class") {
            if std::mem::replace(&mut class_given, true) {
                return Err(inner.error("`class` is given twice"));
            }
            options.class = parse_class_list(&inner)?;
            Ok(())
        } else if inner.path.is_ident("message") {
            if options.message.is_some() {
                return Err(inner.error("`message` is given twice"));
            }
            let message: syn::LitStr = inner.value()?.parse()?;
            if message.value().is_empty() {
                return Err(syn::Error::new_spanned(
                    message,
                    "`message` can't be empty",
                ));
            }
            options.message = Some(message.value());
            Ok(())
        } else if inner.path.is_ident("refuse") {
            if std::mem::replace(&mut refuse_given, true) {
                return Err(inner.error("`refuse` is given twice"));
            }
            let refuse: syn::LitStr = inner.value()?.parse()?;
            if refuse.value() != "every_read" {
                return Err(syn::Error::new_spanned(
                    refuse,
                    "`refuse` takes \"every_read\": the field methods then refuse a restored pointer \
                     on `names()` and on a name that is not a field too",
                ));
            }
            options.every_read = true;
            Ok(())
        } else {
            Err(inner.error(
                "unknown `restored` option; expected `class = \"...\"` (or `class = [\"...\", ...]`), `message = \"...\"` and `refuse = \"every_read\"`",
            ))
        }
    })?;
    Ok(options)
}

/// The arguments of `field_error(...)`: `class = "..."` or `class = ["...",
/// ...]`, `message = "..."` and `no_field_hint = "..."`, each once.
fn parse_field_error_options(meta: &syn::meta::ParseNestedMeta) -> syn::Result<FieldErrorOptions> {
    let mut class: Option<Vec<String>> = None;
    let mut message: Option<String> = None;
    let mut no_field_hint: Option<String> = None;
    meta.parse_nested_meta(|inner| {
        if inner.path.is_ident("class") {
            if class.is_some() {
                return Err(inner.error("`class` is given twice"));
            }
            class = Some(parse_class_list(&inner)?);
            Ok(())
        } else if inner.path.is_ident("message") {
            if message.is_some() {
                return Err(inner.error("`message` is given twice"));
            }
            let value: syn::LitStr = inner.value()?.parse()?;
            if value.value().is_empty() {
                return Err(syn::Error::new_spanned(value, "`message` is empty"));
            }
            message = Some(value.value());
            Ok(())
        } else if inner.path.is_ident("no_field_hint") {
            if no_field_hint.is_some() {
                return Err(inner.error("`no_field_hint` is given twice"));
            }
            let value: syn::LitStr = inner.value()?.parse()?;
            if value.value().is_empty() {
                return Err(syn::Error::new_spanned(value, "`no_field_hint` is empty"));
            }
            no_field_hint = Some(value.value());
            Ok(())
        } else {
            Err(inner.error(
                "unknown `field_error` option; expected `class = \"...\"` (or `class = [\"...\", ...]`), `message = \"...\"` and `no_field_hint = \"...\"`",
            ))
        }
    })?;
    Ok(FieldErrorOptions {
        class: class.unwrap_or_default(),
        message,
        no_field_hint,
    })
}

/// Check if a field has the `#[r_data]` attribute.
fn has_r_data_attr(field: &Field) -> bool {
    field.attrs.iter().any(|a| a.path().is_ident("r_data"))
}

/// The last path segment that names the rooted sidecar field type,
/// `miniextendr_api::externalptr::Sidecar<T>`. Its final name is #1857; the
/// derive spells it here only.
const SIDECAR_TYPE_NAME: &str = "Sidecar";

/// The `T` of a `Sidecar<T>` field type, `None` for any other type.
fn sidecar_inner_type(ty: &syn::Type) -> Option<&syn::Type> {
    let syn::Type::Path(type_path) = ty else {
        return None;
    };
    let seg = type_path.path.segments.last()?;
    if seg.ident != SIDECAR_TYPE_NAME {
        return None;
    }
    let syn::PathArguments::AngleBracketed(args) = &seg.arguments else {
        return None;
    };
    let mut types = args.args.iter().filter_map(|arg| match arg {
        syn::GenericArgument::Type(ty) => Some(ty),
        _ => None,
    });
    let inner = types.next()?;
    types.next().is_none().then_some(inner)
}

/// The last path segment that names the marker type of a computed field,
/// `miniextendr_api::externalptr::Computed` (#1883).
const COMPUTED_TYPE_NAME: &str = "Computed";

/// Whether a field type is `Computed`, the marker of a read-only field
/// computed from the Rust value by the function `#[r_data(get = "...")]`
/// names.
fn is_computed_type(ty: &syn::Type) -> bool {
    matches!(ty, syn::Type::Path(type_path)
        if type_path.path.segments.last().is_some_and(|seg| seg.ident == COMPUTED_TYPE_NAME))
}

/// Options for a sidecar field's generated documentation, setters and Rust
/// accessors.
#[derive(Default)]
struct RDataOptions {
    prop_doc: Option<String>,
    setter_invisible: Option<bool>,
    /// `ref`: generate the Rust getter of a `Sidecar<T>` field.
    access_ref: Option<Span>,
    /// `mut`: generate the Rust setter of a `Sidecar<T>` field.
    access_mut: Option<Span>,
    /// `name = "..."`: the field's R name, in place of the Rust identifier
    /// (#1891).
    name: Option<syn::LitStr>,
    /// `get = "path"`: the getter of a `Computed` field, a
    /// `fn(&Self) -> impl IntoR` (#1883).
    get: Option<syn::LitStr>,
}

/// Which Rust accessors a `Sidecar<T>` field gets: `#[r_data(ref)]` the
/// getter, `#[r_data(mut)]` the setter, `#[r_data(ref, mut)]` or a bare
/// `#[r_data]` both.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
struct SidecarAccess {
    get: bool,
    set: bool,
}

/// One item of `#[r_data(...)]`: `ref`, `mut` (both keywords, so
/// `parse_nested_meta` cannot read them) or `key = "value"`.
enum RDataArg {
    Ref(Span),
    Mut(Span),
    KeyValue { key: Ident, value: syn::LitStr },
}

impl syn::parse::Parse for RDataArg {
    fn parse(input: syn::parse::ParseStream) -> syn::Result<Self> {
        let lookahead = input.lookahead1();
        if lookahead.peek(syn::Token![ref]) {
            let token: syn::Token![ref] = input.parse()?;
            Ok(Self::Ref(token.span))
        } else if lookahead.peek(syn::Token![mut]) {
            let token: syn::Token![mut] = input.parse()?;
            Ok(Self::Mut(token.span))
        } else if lookahead.peek(Ident) {
            let key: Ident = input.parse()?;
            let _eq: syn::Token![=] = input.parse()?;
            let value: syn::LitStr = input.parse()?;
            Ok(Self::KeyValue { key, value })
        } else {
            Err(lookahead.error())
        }
    }
}

/// Parse field-level `#[r_data(ref, mut, prop_doc = "...", setter = "visible")]`
/// options.
fn parse_r_data_options(field: &Field) -> syn::Result<RDataOptions> {
    let mut options = RDataOptions::default();
    for attr in &field.attrs {
        if !attr.path().is_ident("r_data") || matches!(attr.meta, syn::Meta::Path(_)) {
            continue;
        }
        let args = attr.parse_args_with(
            syn::punctuated::Punctuated::<RDataArg, syn::Token![,]>::parse_terminated,
        )?;
        for arg in args {
            match arg {
                RDataArg::Ref(span) => {
                    if options.access_ref.replace(span).is_some() {
                        return Err(syn::Error::new(span, "duplicate `ref` option"));
                    }
                }
                RDataArg::Mut(span) => {
                    if options.access_mut.replace(span).is_some() {
                        return Err(syn::Error::new(span, "duplicate `mut` option"));
                    }
                }
                RDataArg::KeyValue { key, value } if key == "prop_doc" => {
                    options.prop_doc = Some(value.value());
                }
                RDataArg::KeyValue { key, value } if key == "setter" => {
                    if options.setter_invisible.is_some() {
                        return Err(syn::Error::new_spanned(key, "duplicate `setter` option"));
                    }
                    options.setter_invisible = Some(match value.value().as_str() {
                        "visible" => false,
                        "invisible" => true,
                        _ => {
                            return Err(syn::Error::new_spanned(
                                value,
                                "setter must be \"visible\" or \"invisible\"",
                            ));
                        }
                    });
                }
                RDataArg::KeyValue { key, value } if key == "name" => {
                    if options.name.is_some() {
                        return Err(syn::Error::new_spanned(key, "duplicate `name` option"));
                    }
                    options.name = Some(value);
                }
                RDataArg::KeyValue { key, value } if key == "get" => {
                    if options.get.is_some() {
                        return Err(syn::Error::new_spanned(key, "duplicate `get` option"));
                    }
                    options.get = Some(value);
                }
                RDataArg::KeyValue { key, .. } => {
                    return Err(syn::Error::new_spanned(
                        &key,
                        format!(
                            "unknown key `{key}`; supported: `ref`, `mut`, `name`, `get`, `prop_doc`, `setter`"
                        ),
                    ));
                }
            }
        }
    }
    if options.setter_invisible.is_some()
        && (is_rsidecar_type(field)
            || is_computed_type(&field.ty)
            || !is_pub(field)
            || field.ident.is_none())
    {
        return Err(syn::Error::new_spanned(
            field,
            "`setter` requires a public named sidecar slot with a setter, not the RSidecar \
             selector or a `Computed` field",
        ));
    }
    if let Some(span) = options.access_ref.or(options.access_mut)
        && sidecar_inner_type(&field.ty).is_none()
    {
        return Err(syn::Error::new(
            span,
            format!(
                "`ref` and `mut` in `#[r_data(...)]` apply to `{SIDECAR_TYPE_NAME}<T>` fields only; \
                 a plain `#[r_data]` field stays a struct field with its R accessors{}",
                if is_computed_type(&field.ty) {
                    format!(
                        ", and a `{COMPUTED_TYPE_NAME}` field is read through its `get` function"
                    )
                } else {
                    String::new()
                }
            ),
        ));
    }
    if let Some(name) = &options.name {
        if is_rsidecar_type(field) {
            return Err(syn::Error::new_spanned(
                name,
                "`name` applies to a sidecar slot, not the RSidecar selector, which has no R name",
            ));
        }
        let value = name.value();
        if value.is_empty() {
            return Err(syn::Error::new_spanned(
                name,
                "an R field name can't be empty",
            ));
        }
        if value == ".ptr" {
            return Err(syn::Error::new_spanned(
                name,
                "`.ptr` is the element that carries the pointer in a list or environment receiver, \
                 so it can't be an R field name",
            ));
        }
        if !crate::naming::is_syntactic_r_name(&value) {
            return Err(syn::Error::new_spanned(
                name,
                format!(
                    "`{value}` is not a syntactic R name; an R field name has letters, digits, `.` and `_` \
                     only, starts with a letter or a `.` not followed by a digit, and is not a reserved word"
                ),
            ));
        }
    }
    match (&options.get, is_computed_type(&field.ty)) {
        (Some(get), false) => {
            return Err(syn::Error::new_spanned(
                get,
                format!(
                    "`get` applies to a `{COMPUTED_TYPE_NAME}` field only: declare the field as \
                     `pub <name>: {COMPUTED_TYPE_NAME}`, and `get` names the function that computes its value"
                ),
            ));
        }
        (None, true) => {
            return Err(syn::Error::new_spanned(
                &field.ty,
                format!(
                    "a `{COMPUTED_TYPE_NAME}` field needs `#[r_data(get = \"Self::f\")]`, the function \
                     `fn(&Self) -> impl IntoR` that computes its value"
                ),
            ));
        }
        _ => {}
    }
    Ok(options)
}

/// Check if a field type is `RSidecar`.
///
/// Returns `true` if the last path segment of the field's type is `RSidecar`,
/// which acts as the selector marker enabling R sidecar accessor generation.
pub(crate) fn is_rsidecar_type(field: &Field) -> bool {
    if let syn::Type::Path(type_path) = &field.ty {
        type_path
            .path
            .segments
            .last()
            .map(|seg| seg.ident == "RSidecar")
            .unwrap_or(false)
    } else {
        false
    }
}

/// Check if a field is public.
fn is_pub(field: &Field) -> bool {
    matches!(field.vis, Visibility::Public(_))
}

/// The kind of sidecar slot, determining how getter/setter FFI functions are generated.
///
/// Each kind maps to a different codegen strategy for reading and writing the
/// slot through R's `.Call` interface:
/// - `Sidecar`: a value in the external pointer's protection list, validated
///   with `TryFromSexp::<T>` on write and stored as R gave it.
/// - Scalars: a struct field, read into R with `Rf_Scalar*`, written with `Rf_as*`.
/// - Conversion: a struct field, converted with the `IntoR`/`TryFromSexp` traits.
/// - Computed: no field; a getter function of the Rust value, no setter.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) enum SlotKind {
    /// `Sidecar<T>` field: the value at this position among the type's
    /// `Sidecar` fields, kept in the external pointer's protection list
    /// (getter returns it, setter validates `value` as a `T` and stores it
    /// there).
    Sidecar(usize),
    /// `Computed` marker field: the getter calls this function, a
    /// `fn(&Self) -> impl IntoR` (a leading `Self` already replaced by the
    /// struct's name), on the live Rust value; there is no setter (#1883).
    Computed(syn::Path),
    /// Scalar struct field `i32` (or `i16`/`i8`), returned as a length-1 integer.
    ScalarInt,
    /// Scalar struct field `f64` (or `f32`), returned as a length-1 double.
    ScalarReal,
    /// Scalar struct field `bool` (or `Rbool`), returned as a length-1 logical.
    ScalarLogical,
    /// Scalar struct field `u8`, returned as a length-1 raw.
    ScalarRaw,
    /// Conversion type -- uses `IntoR`/`TryFromSexp` traits for arbitrary Rust types.
    Conversion,
}

/// Information about a single `#[r_data]`-annotated sidecar slot field.
///
/// Collected during struct field parsing and used to generate FFI getter/setter
/// functions and R wrapper code for each public slot.
pub(crate) struct SidecarSlot {
    /// Rust identifier of the field (e.g., `count`, `name`). The C symbols,
    /// the `R_CallMethodDef` statics and the Rust accessors are named by it.
    pub(crate) name: Ident,
    /// The field's R name: `#[r_data(name = "...")]`, else the Rust
    /// identifier (#1891). Every R-facing string uses it: `.rdata_fields_T`,
    /// the `$` switch labels, the R6 binding / S7 property, the standalone
    /// `T_get_<name>()` / `T_set_<name>()` and the setter's message. A
    /// `Sidecar` field's save slot is named by it too (`SIDECAR_NAMES`, the
    /// name the accessors and `__mx_visit_sidecars` pass, #2215).
    pub(crate) r_name: String,
    /// Rust type of the field, used in conversion-based getter/setter codegen.
    ty: syn::Type,
    /// The field's visibility, which its generated Rust accessors take.
    vis: Visibility,
    /// Whether the field is `pub`. Only public fields get R accessor functions.
    is_public: bool,
    /// Determines the codegen strategy for reading/writing this slot.
    pub(crate) kind: SlotKind,
    /// The Rust accessors of a `Sidecar<T>` field (`#[r_data(ref | mut)]`);
    /// unused by the other kinds.
    access: SidecarAccess,
    /// Optional documentation string for the S7 `@prop` tag.
    /// Sourced from `#[r_data(prop_doc = "...")]`. `None` means no doc was supplied;
    /// a default fallback string is used at emit time.
    prop_doc: Option<String>,
    /// Explicit setter visibility; each generated setter keeps its default when absent.
    setter_invisible: Option<bool>,
}

/// Aggregated sidecar information extracted from struct field analysis.
///
/// Contains everything needed to generate sidecar accessor code: the
/// selector presence, the list of typed slots, and the target class system.
pub(crate) struct SidecarInfo {
    /// Whether the struct contains an `RSidecar`-typed field marked with `#[r_data]`.
    /// At most one selector is allowed per struct.
    has_selector: bool,
    /// The `#[r_data]` slot fields (excluding the RSidecar selector itself),
    /// each carrying its index, kind, and visibility.
    pub(crate) slots: Vec<SidecarSlot>,
    /// The R class system chosen via `#[externalptr(...)]`, controlling the
    /// style of generated R wrapper code.
    class_system: ClassSystem,
}

/// The getter path of a `Computed` field, `#[r_data(get = "Self::f")]`,
/// parsed from the literal; a leading `Self` becomes the struct's name, since
/// the getter is called from a free function the derive emits outside any
/// impl.
fn computed_getter_path(get: &syn::LitStr, struct_name: &Ident) -> syn::Result<syn::Path> {
    let mut path: syn::Path = get.parse().map_err(|err| {
        syn::Error::new_spanned(
            get,
            format!("`get` must be a path to the getter function, e.g. `Self::f`: {err}"),
        )
    })?;
    crate::util::resolve_self(&mut path, struct_name);
    Ok(path)
}

/// R views stored in ordinary Rust fields have no GC owner. Inspect only
/// known views and containers: aliases and user-defined wrappers are opaque to
/// a derive, and a generic argument alone need not be stored (PhantomData).
fn contains_unrooted_r_view(ty: &syn::Type) -> bool {
    if crate::type_inspect::is_rooted_reference(ty) {
        return true;
    }
    match ty {
        syn::Type::Array(t) => contains_unrooted_r_view(&t.elem),
        syn::Type::Slice(t) => contains_unrooted_r_view(&t.elem),
        syn::Type::Tuple(t) => t.elems.iter().any(contains_unrooted_r_view),
        syn::Type::Reference(t) => contains_unrooted_r_view(&t.elem),
        syn::Type::Paren(t) => contains_unrooted_r_view(&t.elem),
        syn::Type::Group(t) => contains_unrooted_r_view(&t.elem),
        syn::Type::Path(t) if t.qself.is_none() => {
            let Some(segment) = t.path.segments.last() else {
                return false;
            };
            match segment.ident.to_string().as_str() {
                "SEXP" | "List" | "ListMut" | "NamedList" | "DataFrame" | "StrVec" | "RCow"
                | "RArray" | "RVector" | "RMatrix" | "RArray3D" | "Factor" | "FactorMut" => true,
                "Option" | "Result" | "Vec" | "VecDeque" | "LinkedList" | "BinaryHeap"
                | "HashSet" | "BTreeSet" | "HashMap" | "BTreeMap" | "Box" | "Rc" | "Arc"
                | "Cow" | "Cell" | "RefCell" | "Mutex" | "RwLock" | "OnceCell" | "OnceLock" => {
                    let syn::PathArguments::AngleBracketed(args) = &segment.arguments else {
                        return false;
                    };
                    args.args.iter().any(|arg| {
                        matches!(arg, syn::GenericArgument::Type(ty) if contains_unrooted_r_view(ty))
                    })
                }
                _ => false,
            }
        }
        _ => false,
    }
}

/// Determine the [`SlotKind`] for a field type by inspecting its last path segment.
///
/// Recognizes `Sidecar<T>`, which takes position `sidecars` (the number of
/// `Sidecar` fields before it), `Computed` with its `get` function, scalar
/// numerics (`i32`, `i16`, `i8`, `f64`, `f32`), booleans (`bool`, `Rbool`),
/// and raw bytes (`u8`). An R view, including one in a standard container,
/// is an error: the struct can't root it.
/// Everything else falls through to [`SlotKind::Conversion`].
fn slot_kind_for_type(
    ty: &syn::Type,
    sidecars: usize,
    get: Option<&syn::LitStr>,
    struct_name: &Ident,
) -> syn::Result<SlotKind> {
    if sidecar_inner_type(ty).is_some() {
        return Ok(SlotKind::Sidecar(sidecars));
    }
    if is_computed_type(ty) {
        // `parse_r_data_options` refused a `Computed` field without `get`.
        let get = get.expect("a Computed field has a `get` option");
        return Ok(SlotKind::Computed(computed_getter_path(get, struct_name)?));
    }
    if contains_unrooted_r_view(ty) {
        let field_type = crate::type_inspect::type_display(ty);
        return Err(syn::Error::new_spanned(
            ty,
            format!(
                "a `{field_type}` sidecar field is not rooted: the GC frees its value once R drops \
                 its own references. Declare the field as `{SIDECAR_TYPE_NAME}<{field_type}>`, which \
                 keeps the value in the external pointer's protection list"
            ),
        ));
    }
    if let syn::Type::Path(type_path) = ty
        && let Some(seg) = type_path.path.segments.last()
    {
        let ident = &seg.ident;
        if ident == SIDECAR_TYPE_NAME {
            return Err(syn::Error::new_spanned(
                ty,
                format!("`{SIDECAR_TYPE_NAME}` takes one type argument: `{SIDECAR_TYPE_NAME}<T>`"),
            ));
        }
        if ident == "i32" || ident == "i16" || ident == "i8" {
            return Ok(SlotKind::ScalarInt);
        }
        if ident == "f64" || ident == "f32" {
            return Ok(SlotKind::ScalarReal);
        }
        if ident == "bool" || ident == "Rbool" {
            return Ok(SlotKind::ScalarLogical);
        }
        if ident == "u8" {
            return Ok(SlotKind::ScalarRaw);
        }
    }
    // Everything else uses conversion
    Ok(SlotKind::Conversion)
}

/// Parse struct fields for sidecar information.
///
/// Iterates over all fields, identifying `#[r_data]` markers. Fields with
/// `RSidecar` type are tracked as selector markers (at most one allowed);
/// all other `#[r_data]` fields become [`SidecarSlot`] entries with their
/// slot kind inferred from the field type.
///
/// Returns `Err` if more than one `RSidecar` field is found.
pub(crate) fn parse_sidecar_info(
    input: &DeriveInput,
    class_system: ClassSystem,
) -> syn::Result<SidecarInfo> {
    let fields = match &input.data {
        syn::Data::Struct(data) => &data.fields,
        _ => {
            return Ok(SidecarInfo {
                has_selector: false,
                slots: vec![],
                class_system,
            });
        }
    };

    let mut selector_fields: Vec<&Field> = vec![];
    let mut slots = vec![];
    let mut sidecars = 0usize;

    for field in fields.iter() {
        if !has_r_data_attr(field) {
            if sidecar_inner_type(&field.ty).is_some() {
                return Err(syn::Error::new_spanned(
                    &field.ty,
                    format!(
                        "a `{SIDECAR_TYPE_NAME}<T>` field needs `#[r_data]`, `#[r_data(ref)]`, \
                         `#[r_data(mut)]` or `#[r_data(ref, mut)]`: the derive attaches only the \
                         fields it knows to the external pointer"
                    ),
                ));
            }
            continue;
        }

        let options = parse_r_data_options(field)?;
        if is_rsidecar_type(field) {
            // RSidecar is the selector marker, not a slot
            selector_fields.push(field);
        } else if let Some(ref ident) = field.ident {
            // Any other type with #[r_data] becomes a slot
            let kind = slot_kind_for_type(&field.ty, sidecars, options.get.as_ref(), &input.ident)?;
            if matches!(kind, SlotKind::Computed(_)) {
                // Only a `pub` `#[r_data]` field reaches R, and a computed
                // field exists for R only.
                if !is_pub(field) {
                    return Err(syn::Error::new_spanned(
                        field,
                        format!(
                            "a `{COMPUTED_TYPE_NAME}` field must be `pub`: it exists only as an R field, \
                             and only `pub` `#[r_data]` fields reach R"
                        ),
                    ));
                }
                // The R6 active bindings and the S7 properties need a setter;
                // a getters-only form for them is #1888.
                if matches!(class_system, ClassSystem::R6 | ClassSystem::S7) {
                    return Err(syn::Error::new_spanned(
                        field,
                        format!(
                            "a `{COMPUTED_TYPE_NAME}` field is not supported under `#[externalptr({})]`: \
                             its R6 active bindings / S7 properties need a setter, and a computed field \
                             has none (#1888). Use an active method / a computed property, or an S3, S4 \
                             or env class",
                            if class_system == ClassSystem::R6 {
                                "r6"
                            } else {
                                "s7"
                            }
                        ),
                    ));
                }
            }
            let access = if matches!(kind, SlotKind::Sidecar(_)) {
                sidecars += 1;
                let (get, set) = (options.access_ref.is_some(), options.access_mut.is_some());
                // A bare `#[r_data]` on a `Sidecar` field means `ref, mut`.
                SidecarAccess {
                    get: get || !set,
                    set: set || !get,
                }
            } else {
                SidecarAccess::default()
            };
            let r_name = options
                .name
                .as_ref()
                .map_or_else(|| crate::naming::ident_name(ident), syn::LitStr::value);
            slots.push(SidecarSlot {
                name: ident.clone(),
                r_name,
                ty: field.ty.clone(),
                vis: field.vis.clone(),
                is_public: is_pub(field),
                kind,
                access,
                prop_doc: options.prop_doc,
                setter_invisible: options.setter_invisible,
            });
        }
    }

    // Check for multiple selectors
    if selector_fields.len() > 1 {
        return Err(syn::Error::new_spanned(
            selector_fields[1],
            "only one RSidecar field is allowed per struct",
        ));
    }

    // Two slots can't share an R name: a renamed field can't take another
    // field's name (the `$` switch and the standalone accessors would clash).
    for (i, slot) in slots.iter().enumerate() {
        if let Some(earlier) = slots[..i].iter().find(|other| other.r_name == slot.r_name) {
            return Err(syn::Error::new(
                slot.name.span(),
                format!(
                    "the R field name `{}` is already taken by the field `{}`; every `#[r_data]` field \
                     of a type needs its own R name (`#[r_data(name = \"...\")]` renames one)",
                    slot.r_name, earlier.name
                ),
            ));
        }
    }

    Ok(SidecarInfo {
        has_selector: !selector_fields.is_empty(),
        slots,
        class_system,
    })
}

/// Whether a slot's C accessors read the `require_live` flag: only a
/// `Sidecar` slot can serve a restored pointer, so only its accessors decide
/// by the flag; the other kinds need the live Rust value whatever it says.
fn uses_require_live(slot: &SidecarSlot) -> bool {
    matches!(slot.kind, SlotKind::Sidecar(_))
}

/// The `require_live` parameter of a slot's C accessors: named for the body
/// to read when the slot uses it, underscored otherwise.
fn require_live_param(slot: &SidecarSlot) -> Ident {
    if uses_require_live(slot) {
        quote::format_ident!("require_live")
    } else {
        quote::format_ident!("_require_live")
    }
}

/// Generate the token stream for a sidecar getter function body.
///
/// Reads the slot and returns it as an R SEXP. The strategy depends on the
/// slot kind:
/// - `Sidecar`: returns the value from the external pointer's protection list,
///   after flushing a live struct's pending value for the field. It needs no
///   live address, so without `require_live` it also reads a pointer that
///   `readRDS` brought back; with it (the field methods of
///   `r_data_accessors`, #1891) a restored pointer is refused.
/// - Scalar kinds: reads the struct field (accessed via the external pointer
///   address) and wraps it with `Rf_Scalar*`.
/// - `Conversion`: clones the struct field and calls `IntoR::into_sexp`.
/// - `Computed`: calls the `get` function on the live struct and converts
///   its value with `IntoR::into_sexp`.
///
/// The body runs inside `with_r_unwind_protect` (see the emission site in
/// [`generate_sidecar_accessors`]). The receiver is the pointer or an object
/// carrying it in `.ptr`, as for an instance method; an argument carrying no
/// pointer, a null pointer address, or a wrong stored type panics with the
/// same `expected ExternalPtr<T>` message the main class-method path uses.
/// The panic is transported as a tagged condition and re-raised by the R
/// wrapper.
fn generate_getter_body(struct_name: &syn::Ident, slot: &SidecarSlot) -> TokenStream {
    let field_name = &slot.name;

    // Helper: the live struct behind the pointer, borrowed shared for the
    // getter. `sidecar_r_struct` panics (caught by the surrounding
    // with_r_unwind_protect and raised as an R error) on a non-pointer, a
    // wrong type, or a pointer without an address (a restored object: the
    // classed errors) instead of silently returning R_NilValue, and while a
    // running method holds the struct mutably (`miniextendr_borrow_conflict`).
    let extract_ref = quote::quote! {
        let __mx_data = ::miniextendr_api::externalptr::sidecar_r_struct::<#struct_name>(x);
        let data: &#struct_name = &__mx_data;
    };

    match &slot.kind {
        SlotKind::Sidecar(index) => {
            quote::quote! {
                unsafe {
                    ::miniextendr_api::externalptr::sidecar_r_get::<#struct_name>(
                        x,
                        #index,
                        ::miniextendr_api::externalptr::sidecar_require_live(require_live),
                    )
                }
            }
        }
        SlotKind::Computed(getter) => {
            // The getter's own conditions (`rust_error!(class = ...)`) are
            // panics the surrounding guard catches, so they reach R with
            // their classes. Naming the marker field is its only Rust use:
            // it keeps `dead_code` quiet and checks the field's type.
            quote::quote! {
                use ::miniextendr_api::into_r::IntoR;
                unsafe {
                    #extract_ref
                    let ::miniextendr_api::externalptr::Computed = data.#field_name;
                    IntoR::into_sexp(#getter(data))
                }
            }
        }
        SlotKind::ScalarInt => {
            quote::quote! {
                use ::miniextendr_api::SEXP;
                unsafe {
                    #extract_ref
                    SEXP::scalar_integer(data.#field_name)
                }
            }
        }
        SlotKind::ScalarReal => {
            quote::quote! {
                use ::miniextendr_api::SEXP;
                unsafe {
                    #extract_ref
                    SEXP::scalar_real(data.#field_name)
                }
            }
        }
        SlotKind::ScalarLogical => {
            quote::quote! {
                use ::miniextendr_api::SEXP;
                unsafe {
                    #extract_ref
                    SEXP::scalar_logical(data.#field_name)
                }
            }
        }
        SlotKind::ScalarRaw => {
            quote::quote! {
                use ::miniextendr_api::SEXP;
                unsafe {
                    #extract_ref
                    SEXP::scalar_raw(data.#field_name)
                }
            }
        }
        SlotKind::Conversion => {
            // Use IntoR trait for conversion (e.g., String -> character). The
            // getter reads the field through a shared borrow, so converting it
            // needs a clone; spanned at the field type, so a type without
            // `Clone` is reported at the field.
            let ty = &slot.ty;
            let span = syn::spanned::Spanned::span(ty);
            let clone = quote::quote_spanned! {span=> <#ty as ::core::clone::Clone>::clone };
            quote::quote! {
                use ::miniextendr_api::into_r::IntoR;
                unsafe {
                    #extract_ref
                    let val: #ty = #clone(&data.#field_name);
                    <#ty as IntoR>::into_sexp(val)
                }
            }
        }
    }
}

/// Generate the token stream for a sidecar setter function body.
///
/// Stores the incoming R SEXP `value` in the slot. The strategy depends on the
/// slot kind:
/// - `Sidecar`: validates `value` with `TryFromSexp::<T>` (a failure raises
///   the conversion error) and stores it in the external pointer's protection
///   list, which roots it; a live struct's pending value for the field is
///   dropped.
/// - Scalar kinds: writes the struct field, using `Rf_as*` or coercion for
///   single-element extraction;
///   an input that doesn't reduce to a single non-NA scalar raises a
///   conversion error instead of silently storing an NA/`false` sentinel.
/// - `Conversion`: uses `TryFromSexp::try_from_sexp`; a failed conversion
///   raises a conversion error instead of silently dropping the write.
///
/// Returns the external pointer `x` (for R's invisible return convention).
/// The body runs inside `with_r_unwind_protect` (see the emission site in
/// [`generate_sidecar_accessors`]); a bad receiver panics with the main-path
/// `expected ExternalPtr<T>` message and conversion failures return a tagged
/// condition SEXP with kind `conversion` — both are re-raised by the R
/// wrapper. Sidecar accessors have no `__miniextendr_call` slot (#344/#348),
/// so the tagged conditions carry null call attribution.
///
/// A `Computed` slot has no setter: the result is empty, and the caller
/// emits none.
fn generate_setter_body(struct_name: &syn::Ident, slot: &SidecarSlot) -> TokenStream {
    let field_name = &slot.name;

    // Helper: the live struct behind the pointer, borrowed exclusively for
    // the setter. Failure modes panic like the getter's
    // (`sidecar_r_struct_mut`) instead of silently no-op'ing, and a running
    // method holding the struct makes it raise `miniextendr_borrow_conflict`.
    let extract_mut = quote::quote! {
        let mut __mx_data =
            ::miniextendr_api::externalptr::sidecar_r_struct_mut::<#struct_name>(x);
        let data: &mut #struct_name = &mut __mx_data;
    };

    // Conversion-failure condition, the argument error of #1594 on the
    // setter's `value` formal: `'<field>' must be <expected>: <reason>` with
    // the field's R-facing expectation. The message names the field, which is
    // what an R6 active binding (`obj$count <- x`) or an S7 property
    // (`obj@count <- x`) user assigned to: their condition call is the
    // binding's anonymous function. `e$param == "value"` (the formal), the
    // field's Rust type is `e$rust_type`, and the crate's
    // `conversion_error_class` applies. A `Conversion` slot's expectation comes
    // from the same type table as an argument's, else from the error at run
    // time, else `invalid '<field>' argument`
    // (`rust_conversion_builder::conversion_value_tokens`); a scalar
    // slot reads its value with `Rf_as*`, which has no error value, so the
    // reason is worded from the rejected value (`from_r::scalar_rejection_reason`).
    let crate_class = crate::crate_config::conversion_error_class();
    // A `Sidecar<T>` slot converts and reports its `T`.
    let value_ty = sidecar_inner_type(&slot.ty).unwrap_or(&slot.ty);
    let rust_type = crate::type_inspect::type_display(value_ty);
    // The message names the field as R knows it.
    let field_r_name = slot.r_name.clone();
    let scalar_err = |expected: &str| -> proc_macro2::TokenStream {
        let prefix = format!("'{field_r_name}' must be {expected}");
        quote::quote! {
            ::miniextendr_api::error_value::conversion_condition_value(
                #prefix,
                "value",
                ::core::option::Option::Some(#rust_type),
                &[#(#crate_class),*],
                ::miniextendr_api::__mx_conversion_err_parts!(
                    ::miniextendr_api::from_r::scalar_rejection_reason(value),
                    true
                ),
                ::core::option::Option::None,
                ::core::option::Option::None,
            )
        }
    };

    // Conversion-failure value of a `Conversion` or `Sidecar` slot: the field
    // type's expectation, else the one the type declares or the error knows at
    // run time (a newtype, a `match_arg` enum field), as for an argument.
    let conversion_err = |ty: &syn::Type| -> proc_macro2::TokenStream {
        let prefix = crate::r_preconditions::conversion_expectation(ty, false)
            .map(|expected| format!("'{field_r_name}' must be {expected}"));
        let declared = crate::rust_conversion_builder::declared_expectation(ty);
        crate::rust_conversion_builder::conversion_value_tokens(
            &crate::rust_conversion_builder::ConversionSubject {
                expected: prefix.as_deref().map_or(
                    crate::rust_conversion_builder::Expected::FromError(Some(&declared)),
                    crate::rust_conversion_builder::Expected::Literal,
                ),
                quoted: &field_r_name,
                param: "value",
                nullable: crate::type_inspect::is_option_type(ty),
                rust_type: &rust_type,
            },
            &crate_class,
            &quote::quote!(::core::option::Option::None),
            syn::spanned::Spanned::span(ty),
        )
    };

    match &slot.kind {
        SlotKind::Computed(_) => TokenStream::new(),
        SlotKind::Sidecar(index) => {
            let err_value = conversion_err(value_ty);
            // The receiver is checked before the value, so a wrong pointer is
            // reported as such whatever the value.
            quote::quote! {
                use ::miniextendr_api::TryFromSexp;
                unsafe {
                    let require_live =
                        ::miniextendr_api::externalptr::sidecar_require_live(require_live);
                    ::miniextendr_api::externalptr::sidecar_r_check::<#struct_name>(x, require_live);
                    if let ::core::result::Result::Err(e) = <#value_ty as TryFromSexp>::try_from_sexp(value) {
                        return #err_value;
                    }
                    ::miniextendr_api::externalptr::sidecar_r_set::<#struct_name>(
                        x, #index, value, require_live,
                    );
                    x
                }
            }
        }
        SlotKind::ScalarInt => {
            let err_value = scalar_err("a number");
            quote::quote! {
                use ::miniextendr_api::SexpExt;
                unsafe {
                    #extract_mut
                    data.#field_name = match value.as_integer() {
                        ::core::option::Option::Some(v) => v,
                        ::core::option::Option::None => return #err_value,
                    };
                    x
                }
            }
        }
        SlotKind::ScalarReal => {
            let err_value = scalar_err("a number");
            quote::quote! {
                use ::miniextendr_api::SexpExt;
                unsafe {
                    #extract_mut
                    data.#field_name = match value.as_real() {
                        ::core::option::Option::Some(v) => v,
                        ::core::option::Option::None => return #err_value,
                    };
                    x
                }
            }
        }
        SlotKind::ScalarLogical => {
            let err_value = scalar_err("TRUE or FALSE");
            quote::quote! {
                use ::miniextendr_api::SexpExt;
                unsafe {
                    #extract_mut
                    data.#field_name = match value.as_logical() {
                        ::core::option::Option::Some(v) => v,
                        ::core::option::Option::None => return #err_value,
                    };
                    x
                }
            }
        }
        SlotKind::ScalarRaw => {
            let err_value = scalar_err("a raw value");
            quote::quote! {
                use ::miniextendr_api::{SexpExt, SEXPTYPE};
                unsafe {
                    #extract_mut
                    let raw_vec = value.coerce(SEXPTYPE::RAWSXP);
                    if raw_vec.len() == 0 {
                        return #err_value;
                    }
                    data.#field_name = raw_vec.raw_elt(0);
                    x
                }
            }
        }
        SlotKind::Conversion => {
            let ty = &slot.ty;
            let err_value = conversion_err(ty);
            quote::quote! {
                use ::miniextendr_api::TryFromSexp;
                unsafe {
                    #extract_mut
                    data.#field_name = match <#ty as TryFromSexp>::try_from_sexp(value) {
                        ::core::result::Result::Ok(val) => val,
                        ::core::result::Result::Err(e) => return #err_value,
                    };
                    x
                }
            }
        }
    }
}

/// Generate R wrapper code (roxygen-annotated R functions) for a single sidecar slot.
///
/// Produces getter and setter R functions that call the corresponding C entry
/// points via `.Call`. The generated R code includes roxygen tags (`@rdname`,
/// `@param`, `@return`, `@export`) for documentation.
///
/// All class systems generate the same standalone function pattern
/// (`Type_get_field` / `Type_set_field`); only the roxygen title suffix
/// differs. Class-specific integration (e.g., R6 active bindings, S7
/// properties) is handled separately by [`generate_class_integration_r_code`].
///
/// Each wrapper body carries the shared tagged-condition guard
/// ([`crate::method_return_builder::standalone_body`]) so Rust-origin
/// panics/conversion failures are re-raised as structured R conditions.
/// Note the sidecar C functions have **no** `.call` slot — the `.Call()`
/// passes no `.call` argument (#344/#348); `sys.call()` inside the guard
/// supplies fallback attribution instead. The last `.Call()` argument is the
/// `require_live` flag: `FALSE` here, so the standalone accessors keep
/// reading a save's `Sidecar` values (#1891).
///
/// `field_name` is the field's R name (`Type_get_<name>()`). A `Computed`
/// field (`setter_c_name` is `None`) gets the getter only.
///
/// `exported` writes them on the type's page with `@export`; otherwise they
/// are internal (`@noRd`, no export), the rendering a type whose class has
/// `$` / `[[` field syntax gets (#1900).
fn generate_r_wrapper_for_slot(
    class_system: ClassSystem,
    type_name: &str,
    field_name: &str,
    getter_c_name: &str,
    setter_c_name: Option<&str>,
    setter_invisible: bool,
    exported: bool,
) -> String {
    // Only the roxygen title suffix differs between class systems.
    let suffix = match class_system {
        ClassSystem::Env => "",
        ClassSystem::R6 => " (for R6)",
        ClassSystem::S3 => " (for S3)",
        ClassSystem::S4 => " (for S4)",
        ClassSystem::S7 => " (for S7)",
        ClassSystem::Vctrs => " (for vctrs)",
    };
    let r_getter_name = format!("{}_get_{}", type_name, field_name);
    let getter_body = crate::method_return_builder::standalone_body(
        &format!(".Call({getter_c_name}, x, FALSE)"),
        ".val",
        "  ",
    );
    let getter_tags = if exported {
        format!(
            "#' @rdname {type_name}\n#' @param x The {type_name} external pointer\n\
             #' @return The value of the `{field_name}` field\n#' @export"
        )
    } else {
        "#' @noRd".to_string()
    };
    let mut out = format!(
        r#"
#' Get `{field}` field from {type}{suffix}
{getter_tags}
{r_getter} <- function(x) {{
  {getter_body}
}}
"#,
        type = type_name,
        field = field_name,
        suffix = suffix,
        r_getter = r_getter_name,
        getter_body = getter_body,
    );
    let Some(setter_c_name) = setter_c_name else {
        return out;
    };
    let r_setter_name = format!("{}_set_{}", type_name, field_name);
    let setter_body = crate::method_return_builder::standalone_body(
        &format!(".Call({setter_c_name}, x, value, FALSE)"),
        if setter_invisible {
            "invisible(x)"
        } else {
            "x"
        },
        "  ",
    );
    let setter_tags = if exported {
        format!(
            "#' @rdname {type_name}\n#' @param x The {type_name} external pointer\n\
             #' @param value The new value to set\n#' @return The {type_name} pointer ({visibility})\n\
             #' @export",
            visibility = if setter_invisible {
                "invisibly"
            } else {
                "visibly"
            },
        )
    } else {
        "#' @noRd".to_string()
    };
    out.push_str(&format!(
        r#"
#' Set `{field}` field on {type}{suffix}
{setter_tags}
{r_setter} <- function(x, value) {{
  {setter_body}
}}
"#,
        type = type_name,
        field = field_name,
        suffix = suffix,
        r_setter = r_setter_name,
        setter_body = setter_body,
    ));
    out
}

/// Generate class-integrated R code for sidecar fields.
///
/// For R6: generates `Type$set("active", "field", ...)` calls that add active bindings
/// referencing the sidecar getter/setter .Call entrypoints.
///
/// For S7: generates `.rdata_properties_Type <- list(...)` with S7::new_property()
/// definitions that can be spliced into the S7 class's properties list.
///
/// Other class systems return empty strings (their standalone accessors suffice).
fn generate_class_integration_r_code(
    class_system: ClassSystem,
    type_name: &str,
    pub_slots: &[&SidecarSlot],
) -> String {
    if pub_slots.is_empty() {
        return String::new();
    }

    // Shared tagged-condition guard (one line); `sys.call()` supplies fallback
    // attribution because the sidecar C functions carry no `.call` slot
    // (#344/#348 — a sidecar `.Call()` passes no `.call` argument).
    let guard =
        |indent: &str| crate::method_return_builder::condition_check_lines(indent).join("\n");

    match class_system {
        ClassSystem::R6 => {
            // Generate $set("active", ...) calls for each sidecar field.
            // These are appended after the R6Class definition and add active bindings
            // that delegate to the sidecar .Call accessors.
            let mut code = String::new();
            code.push_str(&format!(
                "\n# Auto-generated active bindings for {type} sidecar fields.\n",
                type = type_name,
            ));
            code.push_str(
                "# These are applied when `r_data_accessors` is set on the impl block.\n",
            );
            code.push_str(&format!(
                ".rdata_active_bindings_{type} <- function(cls) {{\n\
                 \x20 # R CMD check: self/private are R6 runtime bindings (set by cls$set)\n\
                 \x20 self <- private <- NULL\n",
                type = type_name,
            ));
            for slot in pub_slots {
                // The binding takes the R name; the C symbols keep the Rust
                // identifier (#1891).
                let field = &slot.r_name;
                let rust_field = crate::naming::ident_name(&slot.name);
                // Must match the sidecar accessor's actual C symbol exactly (#1273
                // crate-prefixing) — routed through the shared naming.rs helpers.
                let getter_c = crate::naming::sidecar_getter_c_name(type_name, &rust_field);
                let setter_c = crate::naming::sidecar_setter_c_name(type_name, &rust_field);
                // `FALSE`: the bindings keep reading a save's `Sidecar` values.
                code.push_str(&format!(
                    "  cls$set(\"active\", \"{field}\", function(value) {{\n\
                     \x20   if (missing(value)) {{\n\
                     \x20     .val <- .Call({getter_c}, private$.ptr, FALSE)\n\
                     {getter_guard}\n\
                     \x20     .val\n\
                     \x20   }} else {{\n\
                     \x20     .val <- .Call({setter_c}, private$.ptr, value, FALSE)\n\
                     {setter_guard}\n\
                     \x20     {setter_return}\n\
                     \x20   }}\n\
                     \x20 }}, overwrite = TRUE)\n",
                    field = field,
                    getter_c = getter_c,
                    setter_c = setter_c,
                    getter_guard = guard("      "),
                    setter_guard = guard("      "),
                    setter_return = if slot.setter_invisible.unwrap_or(true) {
                        "invisible(self)"
                    } else {
                        "self"
                    },
                ));
            }
            code.push_str("}\n");
            code
        }
        ClassSystem::S7 => {
            // Generate a helper list of S7::new_property() definitions.
            // The S7 wrapper generator references this when `r_data_accessors` is set.
            let mut code = String::new();
            code.push_str(&format!(
                "\n# Auto-generated S7 property definitions for {type} sidecar fields.\n",
                type = type_name,
            ));
            code.push_str(&format!(
                ".rdata_properties_{type} <- list(\n",
                type = type_name,
            ));
            for (i, slot) in pub_slots.iter().enumerate() {
                // The property takes the R name; the C symbols keep the Rust
                // identifier (#1891).
                let field = &slot.r_name;
                let rust_field = crate::naming::ident_name(&slot.name);
                // Must match the sidecar accessor's actual C symbol exactly (#1273
                // crate-prefixing) — routed through the shared naming.rs helpers.
                let getter_c = crate::naming::sidecar_getter_c_name(type_name, &rust_field);
                let setter_c = crate::naming::sidecar_setter_c_name(type_name, &rust_field);
                let comma = if i < pub_slots.len() - 1 { "," } else { "" };
                // `FALSE`: the properties keep reading a save's `Sidecar` values.
                code.push_str(&format!(
                    "    {field} = S7::new_property(\n\
                     \x20       getter = function(self) {{\n\
                     \x20         .val <- .Call({getter_c}, self@.ptr, FALSE)\n\
                     {getter_guard}\n\
                     \x20         .val\n\
                     \x20       }},\n\
                     \x20       setter = function(self, value) {{\n\
                     \x20         .val <- .Call({setter_c}, self@.ptr, value, FALSE)\n\
                     {setter_guard}\n\
                     \x20         {setter_return}\n\
                     \x20       }}\n\
                     \x20   ){comma}\n",
                    field = field,
                    getter_c = getter_c,
                    setter_c = setter_c,
                    getter_guard = guard("          "),
                    setter_guard = guard("          "),
                    setter_return = if slot.setter_invisible.unwrap_or(false) {
                        "invisible(self)"
                    } else {
                        "self"
                    },
                    comma = comma,
                ));
            }
            code.push_str(")\n");
            code
        }
        // Other class systems don't need class-integrated code
        _ => String::new(),
    }
}

/// Generate the R helpers the `$` / `[[` field methods of `r_data_accessors`
/// share on S3, S4 and env classes (#1848): the field names, a getter and a
/// setter `switch()` over the fields' `.Call()`s, the classed
/// `miniextendr_no_field` error naming the fields, the classes the methods
/// put in front of their own errors (`field_error`, `NULL` without them,
/// #1899), and the liveness check of `restored(refuse = "every_read")`
/// with the flag that gates it (`FALSE` and a stub without it, #1901).
///
/// Prepared for every type with R accessors, whatever `#[externalptr(...)]`
/// names, and bundled with its internal accessor rendering. The writer selects
/// that rendering only when an impl enables field syntax, so the impl's option
/// never depends on the derive attribute. The
/// helpers are named by the Rust type ([`crate::naming::rdata_helper_name`]);
/// the field names and the `switch()` labels are the fields' R names, in
/// declared order, computed fields included (#1891, #1883).
///
/// Every arm passes `TRUE` as the accessor's `require_live` flag, so the
/// field methods refuse a pointer restored from a saved session (the
/// standalone accessors pass `FALSE` and keep reading its `Sidecar` values).
/// The accessors return a failed conversion or a panic as a tagged condition
/// value with no call; the calling method raises it with its own frame as
/// the fallback, so the condition reports `x$keys <- value`. A computed
/// field's setter arm raises `miniextendr_read_only_field` itself, with the
/// calling method's frame (`parent.frame()`) resolved the same way. The
/// liveness check returns the same kind of value, which the method raises.
///
/// `field_error(no_field_hint = "...")` adds a sentence after the field list
/// of the `miniextendr_no_field` message, each `%s` in it replaced by the
/// name asked for (#2112). The hint is split on `%s` here and pasted around
/// the name, so any other `%` or `\` in it, or in the name, stays as written.
fn generate_field_syntax_helpers(
    type_name: &str,
    pub_slots: &[&SidecarSlot],
    field_error: &[String],
    no_field_hint: Option<&str>,
    every_read: bool,
) -> String {
    use crate::naming::{RDataHelper, rdata_helper_name};

    let error_class_var = rdata_helper_name(RDataHelper::ErrorClass, type_name);
    let names = pub_slots
        .iter()
        .map(|slot| format!("\"{}\"", slot.r_name))
        .collect::<Vec<_>>()
        .join(", ");
    let listed = pub_slots
        .iter()
        .map(|slot| format!("`{}`", slot.r_name))
        .collect::<Vec<_>>()
        .join(", ");
    // `switch()` arm labels are R symbols: a raw identifier such as `r#for`
    // becomes the reserved word `for`, which needs backticks. The C symbols
    // are named by the Rust identifier.
    let arms = |setter: bool| {
        pub_slots
            .iter()
            .map(|slot| {
                let rust_field = crate::naming::ident_name(&slot.name);
                let call = match (&slot.kind, setter) {
                    // The message names the receiver's R class (#1920), else
                    // the Rust type.
                    (SlotKind::Computed(_), true) => format!(
                        "stop(errorCondition(sprintf(\"`{field}` of `%s` is computed from the Rust \
                         value and can't be assigned\", if (is.null(oldClass(x))) \"{type_name}\" else oldClass(x)[[1L]]), \
                         class = c({error_class_var}, \"miniextendr_read_only_field\"), \
                         call = .miniextendr_frame_call(parent.frame())))",
                        field = slot.r_name,
                    ),
                    (_, true) => format!(
                        ".Call({}, x, value, TRUE)",
                        crate::naming::sidecar_setter_c_name(type_name, &rust_field)
                    ),
                    (_, false) => format!(
                        ".Call({}, x, TRUE)",
                        crate::naming::sidecar_getter_c_name(type_name, &rust_field)
                    ),
                };
                format!("  {} = {call}", crate::naming::r_def_name(&slot.r_name))
            })
            .collect::<Vec<_>>()
            .join(",\n")
    };
    let error_class = if field_error.is_empty() {
        "NULL".to_string()
    } else {
        format!(
            "c({})",
            field_error
                .iter()
                .map(|class| format!("\"{}\"", crate::naming::r_string_escape(class)))
                .collect::<Vec<_>>()
                .join(", ")
        )
    };
    // Without the option the methods never call the check (the flag is
    // `FALSE`), but they name it, and `R CMD check` notes a call to a binding
    // that is no function.
    let live = if every_read {
        format!(
            "function(x, raise) .Call({}, x, raise)",
            crate::naming::sidecar_live_c_name(type_name)
        )
    } else {
        "function(x, raise) TRUE".to_string()
    };
    let every_read = if every_read { "TRUE" } else { "FALSE" };
    let no_field_message =
        format!("sprintf(\"`%s` is not a field of `%s`; its fields are {listed}\", name, cls)");
    let no_field_message = match no_field_hint {
        None => no_field_message,
        Some(hint) => {
            let hint = hint
                .split("%s")
                .map(|part| format!("\"{}\"", crate::naming::r_string_escape(part)))
                .collect::<Vec<_>>()
                .join(", name, ");
            format!("paste0({no_field_message}, \". \", {hint})")
        }
    };
    format!(
        "\n# Field syntax helpers for {type_name} sidecar fields, shared by the `$` / `[[`\n\
         # methods `r_data_accessors` generates on S3, S4 and env classes. The `TRUE`\n\
         # is the accessors' `require_live` flag: the methods refuse a restored pointer.\n\
         {fields_var} <- c({names})\n\
         {get_fn} <- function(x, name) switch(name,\n{get_arms})\n\
         {set_fn} <- function(x, name, value) switch(name,\n{set_arms})\n\
         {error_class_var} <- {error_class}\n\
         {no_field_fn} <- function(name, env, cls) stop(errorCondition(\n\
         \x20 {no_field_message},\n\
         \x20 class = c({error_class_var}, \"miniextendr_no_field\"), call = .miniextendr_frame_call(env)))\n\
         {every_read_var} <- {every_read}\n\
         {live_fn} <- {live}\n",
        fields_var = rdata_helper_name(RDataHelper::Fields, type_name),
        get_fn = rdata_helper_name(RDataHelper::Get, type_name),
        set_fn = rdata_helper_name(RDataHelper::Set, type_name),
        no_field_fn = rdata_helper_name(RDataHelper::NoField, type_name),
        every_read_var = rdata_helper_name(RDataHelper::EveryRead, type_name),
        live_fn = rdata_helper_name(RDataHelper::Live, type_name),
        get_arms = arms(false),
        set_arms = arms(true),
    )
}

/// Generate sidecar accessor constants and `extern "C-unwind"` functions.
///
/// For each public `#[r_data]` field, generates:
/// - A getter FFI function (`C_<crate>__mx_rdata_get_Type_field`)
/// - A setter FFI function (`C_<crate>__mx_rdata_set_Type_field`)
/// - `R_CallMethodDef` entries for routine registration
/// - R wrapper function code (roxygen-documented)
/// - Class-integration code for R6 / S7 (active bindings / properties)
/// - The helpers of the S3 / S4 / env field methods
///   ([`generate_field_syntax_helpers`])
///
/// - With `restored(refuse = "every_read")`, the liveness check
///   (`C_<crate>__mx_rdata_live_Type`, #1901) the field methods call
///
/// The generated statics are:
/// - `__MX_CALL_DEF_RDATA_*`: the `R_CallMethodDef` entries
/// - `R_WRAPPERS_RDATA_{Type}`: the R6 / S7 integration, when present
/// - `R_SIDECAR_ACCESSORS_{Type}`: the standalone accessors, exported and
///   internal, which the wrapper writer picks between by the class's field
///   syntax (`registry::SidecarAccessorsEntry`, #1900). Only the internal
///   rendering includes the field-syntax helpers.
///
/// Returns `Err` if the struct has generic type parameters (`.Call` entrypoints
/// cannot be generic).
fn generate_sidecar_accessors(
    input: &DeriveInput,
    info: &SidecarInfo,
    restored: &RestoredOptions,
    field_error: &FieldErrorOptions,
) -> syn::Result<TokenStream> {
    // Reject generic structs — .Call entrypoints cannot be generic
    if !input.generics.params.is_empty() {
        return Err(syn::Error::new_spanned(
            &input.generics,
            "ExternalPtr does not support generic structs; \
             .Call entrypoints cannot be generic",
        ));
    }

    // If no selector or no public slots, nothing to register
    let pub_slots: Vec<_> = info.slots.iter().filter(|s| s.is_public).collect();
    if !info.has_selector || pub_slots.is_empty() {
        return Ok(quote::quote! {});
    }

    let name = &input.ident;
    let name_str = name.to_string();
    let name_symbol = crate::naming::ident_name(name);

    // Generate getter/setter functions and R wrappers for each pub slot
    let mut c_functions = vec![];
    // The standalone accessors, in the two renderings the wrapper writer
    // picks between (#1900).
    let mut exported = String::new();
    let mut internal = String::new();

    // The exported rendering's page header establishes the @name topic for
    // the accessors' `@rdname`, even if the main class definition uses @noRd.
    let source_line = crate::roxygen::source_tag(format!(
        "Generated by miniextendr from `#[derive(ExternalPtr)]` on `{name_str}`"
    ))
    .map(|line| format!("{line}\n"))
    .unwrap_or_default();
    exported.push_str(&format!(
        r#"
#' @title {type} Sidecar Accessors
#' @name {type}
#' @description Getter and setter functions for `#[r_data]` fields on `{type}`.
{source_line}NULL

"#,
        type = name_str,
    ));

    for slot in &pub_slots {
        let field_name = &slot.name;
        // The C symbols and the `R_CallMethodDef` statics are named by the
        // Rust identifier (`Ident::new` would refuse an R name such as
        // `n.rows`); every R-facing string takes the R name (#1891).
        let field_name_str = crate::naming::ident_name(field_name);
        let r_name = &slot.r_name;
        let computed = matches!(slot.kind, SlotKind::Computed(_));

        // C function names (crate-prefixed for webR cross-package symbol
        // uniqueness — #1273, routed through the shared naming.rs helpers)
        let getter_c_name = crate::naming::sidecar_getter_c_name(&name_str, &field_name_str);
        let setter_c_name = crate::naming::sidecar_setter_c_name(&name_str, &field_name_str);
        let getter_fn_name = Ident::new(&getter_c_name, Span::call_site());
        let setter_fn_name = Ident::new(&setter_c_name, Span::call_site());
        let source_location_doc = crate::source_location_doc(field_name.span());
        let getter_doc = format!(
            "Generated sidecar getter for `{}` field on Rust type `{}`.",
            field_name_str, name_str
        );
        let setter_doc = format!(
            "Generated sidecar setter for `{}` field on Rust type `{}`.",
            field_name_str, name_str
        );
        let getter_doc_lit = syn::LitStr::new(&getter_doc, field_name.span());
        let setter_doc_lit = syn::LitStr::new(&setter_doc, field_name.span());
        // The `require_live` flag the R side passes last: `TRUE` from the
        // field methods, `FALSE` from the standalone accessors, the R6
        // bindings and the S7 properties. Only a `Sidecar` slot reads it.
        let require_live = require_live_param(slot);

        // Generate getter/setter bodies based on slot kind
        let getter_body = generate_getter_body(name, slot);
        let setter_body = generate_setter_body(name, slot);

        // Generate C getter function.
        //
        // The body runs under `with_r_unwind_protect` so Rust panics (and R
        // longjmps during allocation) become a tagged condition SEXP that the
        // R wrapper re-raises, matching the main call-slot path. Sidecar
        // accessors have no `__miniextendr_call` slot (#344/#348), so the
        // transport uses null call attribution; the R wrapper's guard passes
        // `sys.call()` to `.miniextendr_raise_condition` as the fallback.
        // Conditions queued inside the body (a `defer_warning!` in a field's
        // `IntoR` / `TryFromSexp`) are signalled at this call, through the
        // same `mark()` / `finish()` pair the generated wrappers have.
        c_functions.push(quote::quote! {
            #[doc = #getter_doc_lit]
            #[doc = #source_location_doc]
            #[doc = ::core::concat!("Generated from source file `", ::core::file!(), "`.")]
            #[doc(hidden)]
            #[unsafe(no_mangle)]
            #[allow(non_snake_case)]
            pub unsafe extern "C-unwind" fn #getter_fn_name(
                x: ::miniextendr_api::SEXP,
                #require_live: ::miniextendr_api::SEXP,
            ) -> ::miniextendr_api::SEXP {
                let __miniextendr_deferred_mark = ::miniextendr_api::deferred_condition::mark();
                let __miniextendr_value = ::miniextendr_api::unwind_protect::with_r_unwind_protect(
                    || { #getter_body },
                    ::core::option::Option::None,
                );
                unsafe {
                    ::miniextendr_api::deferred_condition::finish(
                        __miniextendr_deferred_mark,
                        __miniextendr_value,
                        ::core::option::Option::None,
                    )
                }
            }
        });

        // Generate R_CallMethodDef entries via distributed slice
        let getter_def_ident = Ident::new(
            &format!("__MX_CALL_DEF_RDATA_GET_{}_{}", name_symbol, field_name_str),
            Span::call_site(),
        );
        let getter_registration =
            crate::call_method_def::call_method_def(&getter_def_ident, &getter_fn_name, 2);
        c_functions.push(quote::quote! {
            #[doc(hidden)]
            #getter_registration
        });

        // A computed field has no setter: no C function, no `CallDef`, no
        // `Type_set_<name>()` (#1883).
        if !computed {
            // Generate C setter function (same unwind/condition transport as
            // the getter above).
            c_functions.push(quote::quote! {
                #[doc = #setter_doc_lit]
                #[doc = #source_location_doc]
                #[doc = ::core::concat!("Generated from source file `", ::core::file!(), "`.")]
                #[doc(hidden)]
                #[unsafe(no_mangle)]
                #[allow(non_snake_case)]
                pub unsafe extern "C-unwind" fn #setter_fn_name(
                    x: ::miniextendr_api::SEXP,
                    value: ::miniextendr_api::SEXP,
                    #require_live: ::miniextendr_api::SEXP,
                ) -> ::miniextendr_api::SEXP {
                    let __miniextendr_deferred_mark = ::miniextendr_api::deferred_condition::mark();
                    let __miniextendr_value = ::miniextendr_api::unwind_protect::with_r_unwind_protect(
                        || { #setter_body },
                        ::core::option::Option::None,
                    );
                    unsafe {
                        ::miniextendr_api::deferred_condition::finish(
                            __miniextendr_deferred_mark,
                            __miniextendr_value,
                            ::core::option::Option::None,
                        )
                    }
                }
            });

            let setter_def_ident = Ident::new(
                &format!("__MX_CALL_DEF_RDATA_SET_{}_{}", name_symbol, field_name_str),
                Span::call_site(),
            );
            let setter_registration =
                crate::call_method_def::call_method_def(&setter_def_ident, &setter_fn_name, 3);
            c_functions.push(quote::quote! {
                #[doc(hidden)]
                #setter_registration
            });
        }

        // Generate R wrapper code based on class system
        let field_start = field_name.span().start();
        let via = if computed {
            format!("`{getter_c_name}`")
        } else {
            format!("`{getter_c_name}` and `{setter_c_name}`")
        };
        let comment = format!(
            "# Generated from Rust source line {}:{}\n# Wraps {} `{}` on Rust type `{}` via {}.\n",
            field_start.line,
            field_start.column + 1,
            if computed {
                "computed field"
            } else {
                "sidecar field"
            },
            r_name,
            name_str,
            via,
        );
        for (out, is_exported) in [(&mut exported, true), (&mut internal, false)] {
            out.push_str(&comment);
            out.push_str(&generate_r_wrapper_for_slot(
                info.class_system,
                &name_str,
                r_name,
                &getter_c_name,
                (!computed).then_some(setter_c_name.as_str()),
                slot.setter_invisible.unwrap_or(true),
                is_exported,
            ));
        }
    }

    // The liveness check of `restored(refuse = "every_read")` (#1901): the
    // field methods ask it before a read that reaches no accessor. `raise`
    // refuses a pointer without its Rust value as the accessors do;
    // otherwise it answers whether the pointer has one.
    if restored.every_read {
        let live_c_name = crate::naming::sidecar_live_c_name(&name_str);
        let live_fn_name = Ident::new(&live_c_name, Span::call_site());
        let live_doc = format!(
            "Generated liveness check of the field methods of Rust type `{name_str}` \
             (`restored(refuse = \"every_read\")`)."
        );
        let live_def_ident = Ident::new(
            &format!("__MX_CALL_DEF_RDATA_LIVE_{name_symbol}"),
            Span::call_site(),
        );
        let live_registration =
            crate::call_method_def::call_method_def(&live_def_ident, &live_fn_name, 2);
        c_functions.push(quote::quote! {
            #[doc = #live_doc]
            #[doc(hidden)]
            #[unsafe(no_mangle)]
            #[allow(non_snake_case)]
            pub unsafe extern "C-unwind" fn #live_fn_name(
                x: ::miniextendr_api::SEXP,
                raise: ::miniextendr_api::SEXP,
            ) -> ::miniextendr_api::SEXP {
                let __miniextendr_deferred_mark = ::miniextendr_api::deferred_condition::mark();
                let __miniextendr_value = ::miniextendr_api::unwind_protect::with_r_unwind_protect(
                    || {
                        use ::miniextendr_api::SEXP;
                        let raise = ::miniextendr_api::externalptr::sidecar_require_live(raise);
                        SEXP::scalar_logical(unsafe {
                            ::miniextendr_api::externalptr::sidecar_r_live::<#name>(x, raise)
                        })
                    },
                    ::core::option::Option::None,
                );
                unsafe {
                    ::miniextendr_api::deferred_condition::finish(
                        __miniextendr_deferred_mark,
                        __miniextendr_value,
                        ::core::option::Option::None,
                    )
                }
            }

            #[doc(hidden)]
            #live_registration
        });
    }

    // R6 / S7 integration is independent of S3 / S4 / env field syntax.
    let r_wrappers = generate_class_integration_r_code(info.class_system, &name_str, &pub_slots);
    // The writer selects this rendering only when an impl enables field
    // syntax. Other types need their standalone accessors, not these helpers.
    internal.push_str(&generate_field_syntax_helpers(
        &name_str,
        &pub_slots,
        &field_error.class,
        field_error.no_field_hint.as_deref(),
        restored.every_read,
    ));

    let const_name_wrappers = Ident::new(
        &format!("R_WRAPPERS_RDATA_{}", name_symbol),
        Span::call_site(),
    );
    let const_name_accessors = Ident::new(
        &format!("R_SIDECAR_ACCESSORS_{}", name_symbol),
        Span::call_site(),
    );
    let source_location_doc = crate::source_location_doc(name.span());
    let source_line_lit = syn::LitInt::new(&name.span().start().line.to_string(), name.span());

    // For S7 class systems, emit MX_S7_SIDECAR_PROPS entries so the S7 codegen
    // can substitute @prop lines for sidecar properties at write time.
    let sidecar_prop_entries = if info.class_system == ClassSystem::S7 {
        let entries: Vec<_> = pub_slots
            .iter()
            .map(|slot| {
                // The property's R name; `registry.rs` derives the
                // `<Class>_get_<name>` collision names from it too.
                let field_str = slot.r_name.as_str();
                let doc_str = slot
                    .prop_doc
                    .as_deref()
                    .unwrap_or("(undocumented sidecar property)");
                // The static is named by the Rust identifier: an R name may
                // hold a `.`.
                let entry_ident = Ident::new(
                    &format!(
                        "__MX_S7_SIDECAR_PROP_{}_{}",
                        name_symbol,
                        crate::naming::ident_name(&slot.name)
                    ),
                    Span::call_site(),
                );
                quote::quote! {
                    #[doc(hidden)]
                    #[cfg_attr(not(target_arch = "wasm32"), ::miniextendr_api::linkme::distributed_slice(::miniextendr_api::registry::MX_S7_SIDECAR_PROPS), linkme(crate = ::miniextendr_api::linkme))]
                    #[allow(non_upper_case_globals)]
                    static #entry_ident: ::miniextendr_api::registry::SidecarPropEntry =
                        ::miniextendr_api::registry::SidecarPropEntry {
                            rust_type: #name_str,
                            field_name: #field_str,
                            prop_doc: #doc_str,
                        };
                }
            })
            .collect();
        quote::quote! { #(#entries)* }
    } else {
        quote::quote! {}
    };

    let class_integration_wrappers = (!r_wrappers.is_empty()).then(|| quote::quote! {
        /// Sidecar accessor R wrapper code via distributed slice.
        #[doc = #source_location_doc]
        #[doc = ::core::concat!("Generated from source file `", ::core::file!(), "`.")]
        #[doc(hidden)]
        #[cfg_attr(not(target_arch = "wasm32"), ::miniextendr_api::linkme::distributed_slice(::miniextendr_api::registry::MX_R_WRAPPERS), linkme(crate = ::miniextendr_api::linkme))]
        #[allow(non_upper_case_globals)]
        static #const_name_wrappers: ::miniextendr_api::registry::RWrapperEntry =
            ::miniextendr_api::registry::RWrapperEntry {
                priority: ::miniextendr_api::registry::RWrapperPriority::Sidecar,
                source_file: ::core::file!(),
                source_line: #source_line_lit,
                content: #r_wrappers,
            };
    });

    Ok(quote::quote! {
        #(#c_functions)*

        #class_integration_wrappers

        /// The standalone sidecar accessors, exported and internal, via
        /// distributed slice.
        #[doc = #source_location_doc]
        #[doc(hidden)]
        #[cfg_attr(not(target_arch = "wasm32"), ::miniextendr_api::linkme::distributed_slice(::miniextendr_api::registry::MX_SIDECAR_ACCESSORS), linkme(crate = ::miniextendr_api::linkme))]
        #[allow(non_upper_case_globals)]
        static #const_name_accessors: ::miniextendr_api::registry::SidecarAccessorsEntry =
            ::miniextendr_api::registry::SidecarAccessorsEntry {
                rust_type: #name_str,
                exported: #exported,
                internal: #internal,
                source_file: ::core::file!(),
                source_line: #source_line_lit,
            };

        #sidecar_prop_entries
    })
}

/// The `Sidecar<T>` slots of a type, in protection-list order.
fn sidecar_slots(info: &SidecarInfo) -> impl Iterator<Item = (usize, &SidecarSlot)> {
    info.slots.iter().filter_map(|slot| match slot.kind {
        SlotKind::Sidecar(index) => Some((index, slot)),
        _ => None,
    })
}

/// Generate the `TypedExternal` trait implementation for the derive target.
///
/// Produces the associated constants:
/// - `TYPE_NAME`: the struct name as a `&'static str`
/// - `TYPE_NAME_CSTR`: null-terminated byte string of the struct name
/// - `TYPE_ID_CSTR`: globally unique ID in the format
///   `"<crate_name>@<crate_version>::<module_path>::<type_name>\0"`,
///   using `CARGO_PKG_NAME`, `CARGO_PKG_VERSION`, and `module_path!()`.
/// - `R_SLOT_COUNT`: the number of `Sidecar<T>` fields, when there are any,
///   with the `__mx_visit_sidecars` hook that hands each of them, with its
///   slot index and name, to the handle (which flushes their pending values
///   into the slots and loads the slots back into them).
///
/// Supports generic structs (generics are forwarded to the impl).
fn generate_typed_external(
    input: &DeriveInput,
    info: &SidecarInfo,
    restored: &RestoredOptions,
    field_error: &FieldErrorOptions,
    rebuild: Option<&syn::Path>,
    any_version: bool,
    display_name: Option<&str>,
) -> TokenStream {
    let name = &input.ident;
    let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();

    let name_str = name.to_string();
    let name_lit = syn::LitStr::new(&name_str, name.span());
    let display_name = display_name.unwrap_or(&name_str);
    let display_lit = syn::LitStr::new(display_name, name.span());
    let name_cstr = syn::LitByteStr::new(format!("{display_name}\0").as_bytes(), name.span());
    // `#[externalptr(restored(class = ..., message = ...))]` (#1891): the
    // package's classes go in front of the `miniextendr_restored*` classes,
    // its message replaces miniextendr's, on every restored refusal of the
    // type (`refuse_restored`, `TypeMismatchError`).
    let restored_class = (!restored.class.is_empty()).then(|| {
        let classes = &restored.class;
        quote::quote! {
            const RESTORED_ERROR_CLASS: &'static [&'static str] = &[#(#classes),*];
        }
    });
    let restored_message = restored.message.as_ref().map(|message| {
        quote::quote! {
            const RESTORED_ERROR_MESSAGE: ::core::option::Option<&'static str> =
                ::core::option::Option::Some(#message);
        }
    });
    // `#[externalptr(field_error(class = ..., message = ...))]` (#1899,
    // #1920): the classes in front of the R accessors' type-mismatch and
    // no-pointer errors, and the package's message for both.
    let field_error_class = (!field_error.class.is_empty()).then(|| {
        let classes = &field_error.class;
        quote::quote! {
            const FIELD_ERROR_CLASS: &'static [&'static str] = &[#(#classes),*];
        }
    });
    let field_error_message = field_error.message.as_ref().map(|message| {
        quote::quote! {
            const FIELD_ERROR_MESSAGE: ::core::option::Option<&'static str> =
                ::core::option::Option::Some(#message);
        }
    });
    // `#[externalptr(rebuild = path)]` (#2146): a restored pointer is
    // rebuilt by `path` on first use. Its `Err` becomes the condition the
    // refusal carries as `e$parent`, through the probe a `Result` return
    // uses: an `RConditionData` error keeps its classes and fields.
    // `any_version` (#2187) lets it rebuild a save by another version too,
    // which the saved slot names make safe to read.
    let rebuild = rebuild.map(|path| {
        let prefix = crate::miniextendr_fn::default_serde_error_prefix();
        let marker = crate::miniextendr_fn::init_marker_path();
        let call = quote::quote_spanned! {syn::spanned::Spanned::span(path)=> #path(saved) };
        let any_version = any_version.then(|| {
            quote::quote! { const REBUILDS_ANY_VERSION: bool = true; }
        });
        quote::quote! {
            const REBUILDS: bool = true;
            #any_version

            fn __mx_rebuild(
                saved: &::miniextendr_api::externalptr::Saved<'_, Self>,
            ) -> ::core::result::Result<Self, ::miniextendr_api::condition::RCondition> {
                match #call {
                    ::core::result::Result::Ok(value) => ::core::result::Result::Ok(value),
                    ::core::result::Result::Err(e) => {
                        let parts = ::miniextendr_api::__mx_result_err_parts!(e, #prefix, #marker);
                        ::core::result::Result::Err(::miniextendr_api::condition::RCondition::Error {
                            message: parts.message,
                            class: parts.class,
                            data: parts.data,
                            call: parts.call,
                        })
                    }
                }
            }
        }
    });
    let sidecars: Vec<_> = sidecar_slots(info).collect();
    // A save names its slots by the fields' R names (#2215), so renaming a
    // Rust field keeps every earlier save readable.
    let r_slot_count = (!sidecars.is_empty()).then(|| {
        let count = sidecars.len();
        let names = sidecars.iter().map(|&(_, slot)| slot.r_name.as_str());
        let visits = sidecars.iter().map(|&(index, slot)| {
            let field = &slot.name;
            let r_name = slot.r_name.as_str();
            quote::quote! { visit(#index, #r_name, &self.#field); }
        });
        quote::quote! {
            const R_SLOT_COUNT: usize = #count;
            const SIDECAR_NAMES: &'static [&'static str] = &[#(#names),*];

            fn __mx_visit_sidecars(
                &self,
                visit: &mut dyn ::core::ops::FnMut(usize, &'static str, &dyn ::miniextendr_api::externalptr::SidecarField),
            ) {
                #(#visits)*
            }
        }
    });

    // TYPE_ID_CSTR format: "<crate_name>@<crate_version>::<module_path>::<type_name>\0"
    //
    // Uses env!("CARGO_PKG_NAME") and env!("CARGO_PKG_VERSION") for the crate identifier,
    // ensuring two packages with the same type name from the same crate+version are compatible,
    // while different crate versions are considered distinct types.
    //
    // The module_path!() may include "crate::" prefix when compiled within the crate,
    // but combined with the explicit crate@version prefix, this is unambiguous.
    quote::quote! {
        impl #impl_generics ::miniextendr_api::externalptr::TypedExternal for #name #ty_generics #where_clause {
            const TYPE_NAME: &'static str = #display_lit;
            const TYPE_NAME_CSTR: &'static [u8] = #name_cstr;
            const TYPE_ID_CSTR: &'static [u8] =
                ::core::concat!(
                    ::core::env!("CARGO_PKG_NAME"), "@", ::core::env!("CARGO_PKG_VERSION"),
                    "::", ::core::module_path!(), "::", #name_lit, "\0"
                ).as_bytes();
            #r_slot_count
            #restored_class
            #restored_message
            #field_error_class
            #field_error_message
            #rebuild
        }
    }
}

/// ALTREP stores its owner in an ordinary ExternalPtr, so it needs the same
/// slot visitor and handle accessors. Only storage is generated here: ALTREP
/// has its own IntoR and registration, and isn't an R class with field methods.
pub(crate) fn generate_altrep_storage(
    input: &DeriveInput,
    class_name: &str,
) -> syn::Result<TokenStream> {
    if let syn::Data::Struct(data) = &input.data {
        for field in &data.fields {
            for attr in field.attrs.iter().filter(|a| a.path().is_ident("r_data")) {
                if sidecar_inner_type(&field.ty).is_none() {
                    return Err(syn::Error::new_spanned(
                        field,
                        "ALTREP #[r_data] fields must be Sidecar<T>; R field accessors belong to ExternalPtr classes",
                    ));
                }
                if matches!(&attr.meta, syn::Meta::List(_)) {
                    attr.parse_nested_meta(|meta| {
                        if meta.path.is_ident("ref") || meta.path.is_ident("mut") {
                            Ok(())
                        } else {
                            Err(meta.error("ALTREP sidecars support only `ref` and `mut` access; they have no R field wrappers"))
                        }
                    })?;
                }
            }
        }
    }
    let info = parse_sidecar_info(input, ClassSystem::Env)?;
    let storage = generate_typed_external(
        input,
        &info,
        &RestoredOptions::default(),
        &FieldErrorOptions::default(),
        None,
        false,
        Some(class_name),
    );
    let accessors = generate_sidecar_rust_accessors(input, &info, false);
    Ok(quote::quote! { #storage #accessors })
}

/// Generate the Rust accessors of each `Sidecar<T>` field, as associated
/// functions of the struct taking an owner handle, with the field's visibility:
/// `fn keys(ptr: &impl SidecarOwner<Self>) -> T` for `#[r_data(ref)]`,
/// `fn set_keys(ptr: &mut impl SidecarOwnerMut<Self>, value: T)` for `#[r_data(mut)]`,
/// both for `#[r_data(ref, mut)]` or a bare `#[r_data]`. The struct holds no
/// reference to its pointer, so there is no accessor on `&self` (#1856).
///
/// A type with a rebuild hook (`rebuilds`) also gets
/// `fn try_keys(saved: &Saved<'_, Self>) -> Option<T>` for every `Sidecar`
/// field: `None` when the save has no slot for it (#2187).
///
/// A non-`pub` accessor is `#[allow(dead_code)]`: it is generated whether or
/// not the crate calls it. The accessors (and the `TypedExternal` hook) read
/// the fields, so rustc sees them used.
fn generate_sidecar_rust_accessors(
    input: &DeriveInput,
    info: &SidecarInfo,
    rebuilds: bool,
) -> TokenStream {
    let methods: Vec<TokenStream> = sidecar_slots(info)
        .flat_map(|(index, slot)| {
            let inner = sidecar_inner_type(&slot.ty).expect("a Sidecar slot has an inner type");
            let field = &slot.name;
            let field_name = crate::naming::ident_name(field);
            // The accessors are named by the Rust field; the save, and the
            // messages R users read, by its R name (#2215).
            let r_name = slot.r_name.as_str();
            let vis = &slot.vis;
            let allow = (!matches!(vis, Visibility::Public(_)))
                .then(|| quote::quote! { #[allow(dead_code)] });
            let mut methods = Vec::with_capacity(3);
            if rebuilds {
                let try_getter = quote::format_ident!("try_{}", field_name);
                let doc = format!(
                    "The value of the `{field_name}` sidecar field as the save `saved` kept \
                     it, in the slot of its R name `{r_name}`, for a rebuild hook; `None` when \
                     the version that saved the object had no slot of that name. On R's main \
                     thread."
                );
                methods.push(quote::quote! {
                    #[doc = #doc]
                    #allow
                    #vis fn #try_getter(
                        saved: &::miniextendr_api::externalptr::Saved<'_, Self>,
                    ) -> ::core::option::Option<#inner> {
                        ::miniextendr_api::externalptr::sidecar_try_saved::<Self, #inner>(
                            saved, #index, #r_name,
                        )
                    }
                });
            }
            if slot.access.get {
                let doc = format!(
                    "The value of the `{field_name}` sidecar field of the object `ptr` holds: \
                     the R value the external pointer keeps, converted to its Rust type (a copy \
                     for a converting type), after moving a pending value into the pointer. On \
                     R's main thread."
                );
                methods.push(quote::quote! {
                    #[doc = #doc]
                    #allow
                    #vis fn #field(ptr: &impl ::miniextendr_api::externalptr::SidecarOwner<Self>) -> #inner {
                        ::miniextendr_api::externalptr::sidecar_get::<Self, #inner>(
                            ptr, #index, #r_name, |this: &Self| &this.#field,
                        )
                    }
                });
            }
            if slot.access.set {
                let setter = quote::format_ident!("set_{}", field_name);
                let doc = format!(
                    "Stores `value` in the `{field_name}` sidecar field of the object `ptr` \
                     holds: in the external pointer's protection list, dropping a pending value. \
                     On R's main thread."
                );
                methods.push(quote::quote! {
                    #[doc = #doc]
                    #allow
                    #vis fn #setter(ptr: &mut impl ::miniextendr_api::externalptr::SidecarOwnerMut<Self>, value: #inner) {
                        ::miniextendr_api::externalptr::sidecar_set::<Self, #inner>(
                            ptr, #index, #r_name, |this: &Self| &this.#field, value,
                        )
                    }
                });
            }
            methods
        })
        .collect();
    if methods.is_empty() {
        return TokenStream::new();
    }
    let name = &input.ident;
    let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
    quote::quote! {
        impl #impl_generics #name #ty_generics #where_clause {
            #(#methods)*
        }
    }
}

/// Generate the `IntoExternalPtr` marker trait impl.
///
/// This marker trait enables the blanket `impl<T: IntoExternalPtr> IntoR for T`
/// in miniextendr-api, allowing the type to be returned directly from functions.
fn generate_into_external_ptr(input: &DeriveInput) -> TokenStream {
    let name = &input.ident;
    let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();

    quote::quote! {
        impl #impl_generics ::miniextendr_api::externalptr::IntoExternalPtr for #name #ty_generics #where_clause {}
    }
}

/// Generate the concrete `IntoRVecElement` impl (issue #1284).
///
/// Lights up the single `impl<T: IntoRVecElement> IntoR for Vec<T>` blanket in
/// miniextendr-api, so `-> Vec<MyType>` returns compile and produce a `VECSXP`
/// of external pointers. The impl must be concrete (not a blanket over
/// `IntoExternalPtr`) because the `MatchArg` bridge already occupies a blanket
/// on `IntoRVecElement` and two blankets would collide (E0119) — the same
/// funnel design `#[derive(IntoR)]` newtypes use (see
/// `miniextendr_api::newtype` module docs).
///
/// GC discipline: `ExternalPtr::collect_into_r_list` allocates each
/// `EXTPTRSXP` directly into the already-protected destination list, so no
/// element is ever live-but-unrooted across a later allocation.
fn generate_into_r_vec_element(input: &DeriveInput) -> TokenStream {
    let name = &input.ident;
    let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();

    quote::quote! {
        impl #impl_generics ::miniextendr_api::IntoRVecElement for #name #ty_generics #where_clause {
            #[inline]
            fn elements_into_sexp(values: ::std::vec::Vec<Self>) -> ::miniextendr_api::SEXP {
                ::miniextendr_api::externalptr::ExternalPtr::<Self>::collect_into_r_list(values)
            }
        }
    }
}

/// Main entry point for `#[derive(ExternalPtr)]`.
///
/// Orchestrates the full derive expansion:
/// 1. Parses `#[externalptr(...)]` attributes for class system selection.
/// 2. Analyzes struct fields for `#[r_data]` sidecar slots.
/// 3. Generates `TypedExternal` impl (type identity for `ExternalPtr<T>`).
/// 4. Generates `IntoExternalPtr` marker impl (enables `IntoR` blanket impl)
///    and a concrete `IntoRVecElement` impl (enables the `IntoR for Vec<T>`
///    blanket, so `-> Vec<MyType>` returns a `VECSXP` of external pointers —
///    #1284). Both are suppressed when `emit_into_r_marker` is `false`, which
///    the struct-level `#[miniextendr(prefer = "native")]` path uses so its
///    concrete `AsRNative` `IntoR` does not collide with the blanket
///    `IntoExternalPtr` `IntoR` (E0119, #1283).
/// 5. Generates sidecar accessor FFI functions, registration constants, and R wrappers.
///
/// Returns the combined token stream of all generated items.
pub fn derive_external_ptr(
    input: DeriveInput,
    emit_into_r_marker: bool,
) -> syn::Result<TokenStream> {
    // Parse the class system and the restored refusal's classes / message
    // from the #[externalptr(...)] attribute
    let ExternalPtrAttrs {
        class_system,
        restored,
        field_error,
        rebuild,
        any_version,
    } = parse_externalptr_attrs(&input)?;

    // Parse sidecar information from struct fields
    let sidecar_info = parse_sidecar_info(&input, class_system)?;

    let typed_external = generate_typed_external(
        &input,
        &sidecar_info,
        &restored,
        &field_error,
        rebuild.as_ref(),
        any_version,
        None,
    );
    let sidecar_rust_accessors =
        generate_sidecar_rust_accessors(&input, &sidecar_info, rebuild.is_some());
    let (into_external_ptr, into_r_vec_element) = if emit_into_r_marker {
        (
            generate_into_external_ptr(&input),
            generate_into_r_vec_element(&input),
        )
    } else {
        (
            proc_macro2::TokenStream::new(),
            proc_macro2::TokenStream::new(),
        )
    };
    let sidecar_accessors =
        generate_sidecar_accessors(&input, &sidecar_info, &restored, &field_error)?;
    let erased_wrapper = generate_erased_wrapper(&input);

    Ok(quote::quote! {
        #typed_external
        #sidecar_rust_accessors
        #into_external_ptr
        #into_r_vec_element
        #sidecar_accessors
        #erased_wrapper
    })
}

/// Generate the type-erased wrapper infrastructure for trait ABI dispatch.
///
/// For `#[derive(ExternalPtr)] struct MyCounter { ... }` generates:
/// - `__MX_TAG_MyCounter` - concrete type tag (FNV-1a hash of module_path + type)
/// - `__MX_BASE_VTABLE_MyCounter` - base vtable with trait/sidecar query
/// - `__mx_wrap_MyCounter` - constructor returning `*mut mx_erased`
fn generate_erased_wrapper(input: &DeriveInput) -> TokenStream {
    let type_ident = &input.ident;

    // Only for non-generic types (generics can't participate in trait dispatch)
    if !input.generics.params.is_empty() {
        return quote::quote! {};
    }

    // Preserve case: distinct Rust types need distinct module-local helpers.
    let type_name = crate::naming::unraw(type_ident);

    let base_vtable_name = quote::format_ident!("__MX_BASE_VTABLE_{}", type_name);
    let concrete_tag_name = quote::format_ident!("__MX_TAG_{}", type_name);
    let wrap_fn_name = quote::format_ident!("__mx_wrap_{}", type_name);
    let source_loc_doc = crate::source_location_doc(type_ident.span());
    let tag_path = format!("::{}", type_ident);

    quote::quote! {
        #[doc(hidden)]
        #[allow(non_upper_case_globals)]
        const #concrete_tag_name: ::miniextendr_api::abi::mx_tag =
            ::miniextendr_api::abi::mx_tag_from_path(::core::concat!(::core::module_path!(), #tag_path));

        #[doc(hidden)]
        #[allow(non_upper_case_globals)]
        static #base_vtable_name: ::miniextendr_api::abi::mx_base_vtable =
            ::miniextendr_api::abi::mx_base_vtable {
                drop: ::miniextendr_api::abi::ErasedObject::<#type_ident>::drop_raw,
                concrete_tag: #concrete_tag_name,
                query: ::miniextendr_api::abi::ErasedObject::<#type_ident>::query,
                data_offset: ::miniextendr_api::abi::ErasedObject::<#type_ident>::DATA_OFFSET,
            };

        #[doc(hidden)]
        #[doc = #source_loc_doc]
        #[allow(non_snake_case)]
        fn #wrap_fn_name(data: #type_ident) -> *mut ::miniextendr_api::abi::mx_erased {
            // SAFETY: the matching base vtable above uses this storage's
            // destructor/offset and this concrete type's registry tag.
            unsafe {
                ::miniextendr_api::abi::ErasedObject::into_raw(data, &#base_vtable_name)
            }
        }
    }
}

#[cfg(test)]
mod tests {
    use super::{ClassSystem, generate_class_integration_r_code, generate_r_wrapper_for_slot};

    const ALL_CLASS_SYSTEMS: [ClassSystem; 6] = [
        ClassSystem::Env,
        ClassSystem::R6,
        ClassSystem::S3,
        ClassSystem::S4,
        ClassSystem::S7,
        ClassSystem::Vctrs,
    ];

    /// Sidecar accessor C functions take only `x` (getter) or `x, value` (setter) —
    /// no `__miniextendr_call` parameter. The R wrappers must pass no `.call` argument
    /// because it would be counted as an extra positional argument by `.Call()`, causing
    /// "Incorrect number of arguments" errors at runtime. Cover every class system variant.
    #[test]
    fn sidecar_accessors_pass_no_call_slot() {
        let getter_c = "C__mx_rdata_get_T_f";
        let setter_c = "C__mx_rdata_set_T_f";

        for cs in ALL_CLASS_SYSTEMS {
            let out =
                generate_r_wrapper_for_slot(cs, "T", "f", getter_c, Some(setter_c), true, true);
            // Correct form: no .call argument — the C function accepts x (getter)
            // or x, value (setter), then the `require_live` flag, `FALSE` for a
            // standalone accessor (#1891).
            assert!(
                out.contains(&format!(".Call({getter_c}, x, FALSE)")),
                "{cs:?} getter should call without .call:\n{out}"
            );
            assert!(
                out.contains(&format!(".Call({setter_c}, x, value, FALSE)")),
                "{cs:?} setter should call without .call:\n{out}"
            );
            // No `.call =` in either spelling.
            assert!(
                !out.contains(".call ="),
                "{cs:?} sidecar wrapper must not pass a .call argument:\n{out}"
            );
        }
    }

    /// Every sidecar R wrapper (getter and setter, all class systems) must
    /// carry the tagged-condition guard so Rust panics / conversion failures
    /// transported by `with_r_unwind_protect(…, None)` are re-raised as
    /// structured R conditions instead of leaking the tagged SEXP to the user.
    #[test]
    fn sidecar_accessors_reraise_tagged_conditions() {
        let getter_c = "C__mx_rdata_get_T_f";
        let setter_c = "C__mx_rdata_set_T_f";

        for cs in ALL_CLASS_SYSTEMS {
            let out =
                generate_r_wrapper_for_slot(cs, "T", "f", getter_c, Some(setter_c), true, true);
            assert_eq!(
                out.matches(".miniextendr_raise_condition(.val, sys.call())")
                    .count(),
                2,
                "{cs:?} getter+setter should each carry the condition guard:\n{out}"
            );
            // A computed field gets the getter only (#1883).
            let out = generate_r_wrapper_for_slot(cs, "T", "f", getter_c, None, true, true);
            assert!(out.contains("T_get_f <- function(x)"), "{out}");
            assert!(!out.contains("T_set_f"), "{out}");
            assert_eq!(
                out.matches(".miniextendr_raise_condition(.val, sys.call())")
                    .count(),
                1,
                "{cs:?} computed getter should carry the condition guard:\n{out}"
            );
        }
    }

    /// A sidecar setter's conversion failure is the argument error of #1594
    /// on its `value` formal (`e$param`), naming the field: `'f' must be
    /// <expected>`, the field's Rust type as `e$rust_type`, and the reason probed from the error (a
    /// `Conversion` slot) or worded from the rejected value (a scalar slot).
    #[test]
    fn sidecar_setter_raises_the_argument_error() {
        let body = |ty: syn::Type, kind: super::SlotKind| {
            let slot = super::SidecarSlot {
                name: syn::Ident::new("f", proc_macro2::Span::call_site()),
                r_name: String::from("f"),
                ty,
                vis: syn::parse_quote!(pub),
                is_public: true,
                kind,
                access: super::SidecarAccess::default(),
                prop_doc: None,
                setter_invisible: None,
            };
            super::generate_setter_body(
                &syn::Ident::new("T", proc_macro2::Span::call_site()),
                &slot,
            )
            .to_string()
        };

        let s = body(syn::parse_quote!(i32), super::SlotKind::ScalarInt);
        assert!(s.contains("\"'f' must be a number\" , \"value\""), "{s}");
        assert!(s.contains("scalar_rejection_reason (value)"), "{s}");
        assert!(s.contains("Some (\"i32\")"), "{s}");
        assert!(s.contains("__mx_conversion_err_parts ! ("), "{s}");
        assert!(!s.contains("failed to convert"), "{s}");

        let s = body(syn::parse_quote!(bool), super::SlotKind::ScalarLogical);
        assert!(s.contains("\"'f' must be TRUE or FALSE\""), "{s}");

        let s = body(syn::parse_quote!(Vec<String>), super::SlotKind::Conversion);
        assert!(s.contains("\"'f' must be character\" , \"value\""), "{s}");
        assert!(s.contains("Some (\"Vec<String>\")"), "{s}");
        assert!(s.contains(", true)"), "{s}");

        // No static expectation: the error may supply one at run time (a
        // `match_arg` enum field), else `invalid 'f' argument`.
        let s = body(syn::parse_quote!(MyType), super::SlotKind::Conversion);
        assert!(s.contains("__mx_conversion_expectation ! (e)"), "{s}");
        assert!(s.contains("conversion_prefix (\"f\" , false ,"), "{s}");
        assert!(
            s.contains(") , \"value\" , :: core :: option :: Option :: Some (\"MyType\")"),
            "{s}"
        );
        assert!(s.contains("Some (\"MyType\")"), "{s}");
    }

    /// The R6 active-binding and S7 property integration code also call the
    /// sidecar C entrypoints directly; they need the same guard (with
    /// `sys.call()` fallback attribution) and must not pass `.call =`.
    #[test]
    fn sidecar_class_integration_reraises_tagged_conditions() {
        let slot = super::SidecarSlot {
            name: syn::Ident::new("f", proc_macro2::Span::call_site()),
            r_name: String::from("f"),
            ty: syn::parse_quote!(i32),
            vis: syn::parse_quote!(pub),
            is_public: true,
            kind: super::SlotKind::ScalarInt,
            access: super::SidecarAccess::default(),
            prop_doc: None,
            setter_invisible: None,
        };
        let slots = [&slot];

        for cs in [ClassSystem::R6, ClassSystem::S7] {
            let out = generate_class_integration_r_code(cs, "T", &slots);
            assert_eq!(
                out.matches(".miniextendr_raise_condition(.val, sys.call())")
                    .count(),
                2,
                "{cs:?} integration getter+setter should each carry the condition guard:\n{out}"
            );
            assert!(
                !out.contains(".call ="),
                "{cs:?} integration code must not pass a .call argument:\n{out}"
            );
            // The bindings / properties keep reading a save: `FALSE` as the
            // accessors' `require_live` flag (#1891).
            let getter_c = crate::naming::sidecar_getter_c_name("T", "f");
            let setter_c = crate::naming::sidecar_setter_c_name("T", "f");
            assert!(
                out.contains(&format!(".Call({getter_c}, ")) && out.contains(", FALSE)"),
                "{out}"
            );
            assert!(
                out.contains(&format!(".Call({setter_c}, ")) && out.contains(", value, FALSE)"),
                "{out}"
            );
        }
    }

    /// `#[r_data(name = "...")]` renames the R field: the R6 binding, the S7
    /// property and its `@prop` entry, the standalone accessors and the field
    /// list use the R name, and so does a save's slot name (#2215); the C
    /// symbols, the `CallDef` statics and the Rust accessors keep the Rust
    /// identifier (#1891).
    #[test]
    fn r_data_name_renames_the_r_field_only() {
        let input: syn::DeriveInput = syn::parse_str(
            "struct Engine { #[r_data] _r: RSidecar, #[r_data(name = \"keys\")] pub r_keys: Sidecar<Vec<i32>>, \
             #[r_data(name = \"n.rows\")] pub n_rows: i32 }",
        )
        .unwrap();
        let info = super::parse_sidecar_info(&input, ClassSystem::R6).unwrap();
        assert_eq!(info.slots[0].r_name, "keys");
        assert_eq!(info.slots[1].r_name, "n.rows");
        let pub_slots: Vec<_> = info.slots.iter().collect();

        let helpers = super::generate_field_syntax_helpers("Engine", &pub_slots, &[], None, false);
        assert!(
            helpers.contains(".rdata_fields_Engine <- c(\"keys\", \"n.rows\")\n"),
            "{helpers}"
        );
        let getter = crate::naming::sidecar_getter_c_name("Engine", "r_keys");
        assert!(
            helpers.contains(&format!("  keys = .Call({getter}, x, TRUE)")),
            "{helpers}"
        );
        assert!(
            helpers.contains("its fields are `keys`, `n.rows`"),
            "{helpers}"
        );

        let r6 = super::generate_class_integration_r_code(ClassSystem::R6, "Engine", &pub_slots);
        assert!(r6.contains("cls$set(\"active\", \"keys\","), "{r6}");
        assert!(
            r6.contains(&format!(".Call({getter}, private$.ptr, FALSE)")),
            "{r6}"
        );
        assert!(!r6.contains("\"r_keys\""), "{r6}");
        let s7 = super::generate_class_integration_r_code(ClassSystem::S7, "Engine", &pub_slots);
        assert!(s7.contains("    keys = S7::new_property("), "{s7}");

        let out = super::derive_external_ptr(input, true).unwrap().to_string();
        assert!(out.contains("Engine_get_keys <- function(x)"), "{out}");
        assert!(
            out.contains("Engine_set_keys <- function(x, value)"),
            "{out}"
        );
        assert!(out.contains("Engine_get_n.rows <- function(x)"), "{out}");
        assert!(!out.contains("Engine_get_r_keys"), "{out}");
        assert!(out.contains(&getter), "{out}");
        assert!(
            out.contains("__MX_CALL_DEF_RDATA_GET_Engine_r_keys"),
            "{out}"
        );
        assert!(
            out.contains("__MX_CALL_DEF_RDATA_GET_Engine_n_rows"),
            "{out}"
        );
        // The Rust accessors keep the Rust name; the visitor hook, which
        // names the save's slots, passes the R name (#2215).
        assert!(out.contains("pub fn r_keys (ptr :"), "{out}");
        assert!(out.contains("pub fn set_r_keys (ptr :"), "{out}");
        assert!(
            out.contains("visit (0usize , \"keys\" , & self . r_keys)"),
            "{out}"
        );
        // The setter's message names the R field.
        assert!(out.contains("'n.rows' must be a number"), "{out}");
    }

    /// The R name must be non-empty, syntactic, unique, not `.ptr`, and not
    /// on the selector.
    #[test]
    fn r_data_name_is_checked() {
        let refused = |source: &str| {
            let input: syn::DeriveInput = syn::parse_str(source).unwrap();
            super::parse_sidecar_info(&input, ClassSystem::Env)
                .err()
                .map(|err| err.to_string())
                .unwrap_or_else(|| panic!("`{source}` must be refused"))
        };
        let message = refused("struct E { #[r_data(name = \"\")] pub count: i32 }");
        assert!(message.contains("can't be empty"), "{message}");
        let message = refused("struct E { #[r_data(name = \".ptr\")] pub count: i32 }");
        assert!(message.contains("`.ptr` is the element"), "{message}");
        let message = refused("struct E { #[r_data(name = \"n rows\")] pub count: i32 }");
        assert!(message.contains("not a syntactic R name"), "{message}");
        let message = refused("struct E { #[r_data(name = \"for\")] pub count: i32 }");
        assert!(message.contains("not a syntactic R name"), "{message}");
        let message = refused(
            "struct E { #[r_data] pub keys: i32, #[r_data(name = \"keys\")] pub r_keys: Sidecar<Vec<i32>> }",
        );
        assert!(
            message.contains("`keys` is already taken by the field `keys`"),
            "{message}"
        );
        let message =
            refused("struct E { #[r_data(name = \"r\")] _r: RSidecar, #[r_data] pub count: i32 }");
        assert!(message.contains("not the RSidecar selector"), "{message}");
        let message = refused("struct E { #[r_data(name = \"a\", name = \"b\")] pub count: i32 }");
        assert!(message.contains("duplicate `name`"), "{message}");
    }

    /// A `Computed` field (#1883): its getter arm calls the `get` function on
    /// the live struct (a leading `Self` resolved to the type), it takes its
    /// declared place among the other fields, it gets no setter C function,
    /// `CallDef` or `Type_set_<f>()`, and the setter switch raises
    /// `miniextendr_read_only_field` for it.
    #[test]
    fn computed_fields_get_a_getter_and_a_read_only_setter_arm() {
        let input: syn::DeriveInput = syn::parse_str(
            "struct Engine { #[r_data] _r: RSidecar, \
             #[r_data(get = \"Self::group_by\")] pub group_by: Computed, \
             #[r_data(name = \"keys\")] pub r_keys: Sidecar<Vec<i32>>, \
             #[r_data(get = \"n_rows_of\")] pub n_rows: Computed, \
             #[r_data] pub base: i32 }",
        )
        .unwrap();
        let info = super::parse_sidecar_info(&input, ClassSystem::S3).unwrap();
        let kinds: Vec<_> = info.slots.iter().map(|slot| slot.kind.clone()).collect();
        assert_eq!(
            kinds,
            [
                super::SlotKind::Computed(syn::parse_quote!(Engine::group_by)),
                super::SlotKind::Sidecar(0),
                super::SlotKind::Computed(syn::parse_quote!(n_rows_of)),
                super::SlotKind::ScalarInt,
            ]
        );
        let name = syn::Ident::new("Engine", proc_macro2::Span::call_site());
        let getter = super::generate_getter_body(&name, &info.slots[0]).to_string();
        assert!(
            getter.contains("sidecar_r_struct :: < Engine > (x)"),
            "{getter}"
        );
        assert!(
            getter.contains("IntoR :: into_sexp (Engine :: group_by (data))"),
            "{getter}"
        );
        assert!(
            super::generate_setter_body(&name, &info.slots[0]).is_empty(),
            "a computed field has no setter body"
        );

        let pub_slots: Vec<_> = info.slots.iter().collect();
        let helpers = super::generate_field_syntax_helpers("Engine", &pub_slots, &[], None, false);
        assert!(
            helpers.contains(
                ".rdata_fields_Engine <- c(\"group_by\", \"keys\", \"n_rows\", \"base\")\n"
            ),
            "{helpers}"
        );
        let group_by_getter = crate::naming::sidecar_getter_c_name("Engine", "group_by");
        assert!(
            helpers.contains(&format!("  group_by = .Call({group_by_getter}, x, TRUE),")),
            "{helpers}"
        );
        assert!(
            helpers.contains(
                "  group_by = stop(errorCondition(sprintf(\"`group_by` of `%s` is computed from the Rust \
                 value and can't be assigned\", if (is.null(oldClass(x))) \"Engine\" else oldClass(x)[[1L]]), \
                 class = c(.rdata_error_class_Engine, \"miniextendr_read_only_field\"), \
                 call = .miniextendr_frame_call(parent.frame()))),"
            ),
            "{helpers}"
        );
        let keys_setter = crate::naming::sidecar_setter_c_name("Engine", "r_keys");
        assert!(
            helpers.contains(&format!("  keys = .Call({keys_setter}, x, value, TRUE),")),
            "{helpers}"
        );

        let out = super::derive_external_ptr(input, true).unwrap().to_string();
        assert!(out.contains("Engine_get_group_by <- function(x)"), "{out}");
        assert!(!out.contains("Engine_set_group_by"), "{out}");
        assert!(
            out.contains("__MX_CALL_DEF_RDATA_GET_Engine_group_by"),
            "{out}"
        );
        assert!(
            !out.contains("__MX_CALL_DEF_RDATA_SET_Engine_group_by"),
            "{out}"
        );
        assert!(
            !out.contains(&crate::naming::sidecar_setter_c_name("Engine", "group_by")),
            "{out}"
        );
        assert!(
            out.contains("Engine_set_keys <- function(x, value)"),
            "{out}"
        );
        // Only the `Sidecar` field's accessors read the flag; the others take
        // it unused.
        assert!(
            out.contains("_require_live : :: miniextendr_api :: SEXP"),
            "{out}"
        );
        assert!(out.contains("sidecar_require_live (require_live)"), "{out}");
    }

    /// The `Computed` compile errors: `get` on another type, no `get`,
    /// `ref` / `mut` / `setter` on it, a non-`pub` one, and one under R6 / S7.
    #[test]
    fn computed_fields_are_checked() {
        let refused = |source: &str, system: ClassSystem| {
            let input: syn::DeriveInput = syn::parse_str(source).unwrap();
            super::parse_sidecar_info(&input, system)
                .err()
                .map(|err| err.to_string())
                .unwrap_or_else(|| panic!("`{source}` must be refused"))
        };
        let message = refused(
            "struct E { #[r_data(get = \"Self::f\")] pub count: i32 }",
            ClassSystem::S3,
        );
        assert!(
            message.contains("`get` applies to a `Computed` field only"),
            "{message}"
        );
        let message = refused(
            "struct E { #[r_data] pub count: Computed }",
            ClassSystem::S3,
        );
        assert!(
            message.contains("needs `#[r_data(get = \"Self::f\")]`"),
            "{message}"
        );
        let message = refused(
            "struct E { #[r_data(ref, get = \"Self::f\")] pub count: Computed }",
            ClassSystem::S3,
        );
        assert!(
            message.contains("read through its `get` function"),
            "{message}"
        );
        let message = refused(
            "struct E { #[r_data(setter = \"visible\", get = \"Self::f\")] pub count: Computed }",
            ClassSystem::S3,
        );
        assert!(
            message.contains("not the RSidecar selector or a `Computed` field"),
            "{message}"
        );
        let message = refused(
            "struct E { #[r_data(get = \"Self::f\")] count: Computed }",
            ClassSystem::S3,
        );
        assert!(message.contains("must be `pub`"), "{message}");
        for (system, name) in [(ClassSystem::R6, "r6"), (ClassSystem::S7, "s7")] {
            let message = refused(
                "struct E { #[r_data(get = \"Self::f\")] pub count: Computed }",
                system,
            );
            assert!(
                message.contains(&format!("not supported under `#[externalptr({name})]`")),
                "{message}"
            );
        }
        let message = refused(
            "struct E { #[r_data(get = \"not a path\")] pub count: Computed }",
            ClassSystem::S3,
        );
        assert!(message.contains("`get` must be a path"), "{message}");
    }

    /// `#[externalptr(restored(class = ..., message = ...))]` (#1891): the
    /// classes (one, or several in order) and the message reach the
    /// `TypedExternal` impl; each alone works; the arguments are checked.
    #[test]
    fn restored_options_reach_the_typed_external_impl() {
        let attrs = |source: &str| {
            let input: syn::DeriveInput = syn::parse_str(source).unwrap();
            super::parse_externalptr_attrs(&input).map(|attrs| (attrs.class_system, attrs.restored))
        };
        let (system, restored) = attrs(
            "#[externalptr(s3, restored(class = [\"pkg_saved\", \"pkg_error\"], message = \"saved; rebuild it\"))] struct E;",
        )
        .unwrap();
        assert_eq!(system, ClassSystem::S3);
        assert_eq!(restored.class, ["pkg_saved", "pkg_error"]);
        assert_eq!(restored.message.as_deref(), Some("saved; rebuild it"));
        let (system, restored) =
            attrs("#[externalptr(restored(class = \"pkg_saved\"))] #[externalptr(s4)] struct E;")
                .unwrap();
        assert_eq!(system, ClassSystem::S4);
        assert_eq!(restored.class, ["pkg_saved"]);
        assert_eq!(restored.message, None);
        let (_, restored) = attrs("#[externalptr(restored(message = \"m\"))] struct E;").unwrap();
        assert!(restored.class.is_empty());
        assert_eq!(restored.message.as_deref(), Some("m"));
        let (_, restored) = attrs("#[externalptr(env)] struct E;").unwrap();
        assert_eq!(restored, super::RestoredOptions::default());

        let refused = |source: &str, expected: &str| {
            let message = attrs(source)
                .err()
                .map(|e| e.to_string())
                .unwrap_or_else(|| panic!("`{source}` must be refused"));
            assert!(message.contains(expected), "`{source}`: {message}");
        };
        // syn refuses the empty parentheses itself.
        refused(
            "#[externalptr(restored())] struct E;",
            "expected nested attribute",
        );
        refused(
            "#[externalptr(restored(class = []))] struct E;",
            "at least one",
        );
        refused(
            "#[externalptr(restored(class = \"\"))] struct E;",
            "can't be empty",
        );
        refused(
            "#[externalptr(restored(message = \"\"))] struct E;",
            "can't be empty",
        );
        refused(
            "#[externalptr(restored(class = \"a\", class = \"b\"))] struct E;",
            "given twice",
        );
        refused(
            "#[externalptr(restored(class = \"a\"), restored(class = \"b\"))] struct E;",
            "given twice",
        );
        refused(
            "#[externalptr(restored(klass = \"a\"))] struct E;",
            "unknown `restored` option",
        );
        refused(
            "#[externalptr(saved)] struct E;",
            "unknown `externalptr` option",
        );

        let input: syn::DeriveInput = syn::parse_str(
            "#[externalptr(s3, restored(class = [\"pkg_saved\", \"pkg_error\"], message = \"saved; rebuild it\"))] struct E { n: i32 }",
        )
        .unwrap();
        let out = super::derive_external_ptr(input, true).unwrap().to_string();
        assert!(
            out.contains(
                "const RESTORED_ERROR_CLASS : & 'static [& 'static str] = & [\"pkg_saved\" , \"pkg_error\"] ;"
            ),
            "{out}"
        );
        assert!(
            out.contains(
                "const RESTORED_ERROR_MESSAGE : :: core :: option :: Option < & 'static str > = :: core :: option :: Option :: Some (\"saved; rebuild it\") ;"
            ),
            "{out}"
        );
        let input: syn::DeriveInput = syn::parse_str("struct E { n: i32 }").unwrap();
        let out = super::derive_external_ptr(input, true).unwrap().to_string();
        assert!(!out.contains("RESTORED_ERROR_"), "{out}");
    }

    /// `rebuild = path, any_version` (#2146, #2187): `any_version` needs
    /// the hook; with it the impl sets `REBUILDS_ANY_VERSION`, and a type
    /// with a hook gets `try_<field>` getters over the save, which take the
    /// `Saved` handle.
    #[test]
    fn rebuild_any_version_option() {
        let attrs = |source: &str| {
            let input: syn::DeriveInput = syn::parse_str(source).unwrap();
            super::parse_externalptr_attrs(&input)
        };
        let parsed =
            attrs("#[externalptr(rebuild = Self::from_saved, any_version)] struct E;").unwrap();
        assert!(parsed.rebuild.is_some());
        assert!(parsed.any_version);
        let parsed = attrs("#[externalptr(rebuild = Self::from_saved)] struct E;").unwrap();
        assert!(!parsed.any_version);
        for source in [
            "#[externalptr(any_version)] struct E;",
            "#[externalptr(r6, any_version)] struct E;",
        ] {
            let message = attrs(source)
                .err()
                .map(|e| e.to_string())
                .unwrap_or_default();
            assert!(
                message.contains("needs `rebuild = path`"),
                "`{source}`: {message}"
            );
        }
        let message = attrs("#[externalptr(rebuild = f, any_version, any_version)] struct E;")
            .err()
            .map(|e| e.to_string())
            .unwrap_or_default();
        assert!(
            message.contains("`any_version` is given twice"),
            "{message}"
        );

        let input: syn::DeriveInput = syn::parse_str(
            "#[externalptr(rebuild = Self::from_saved, any_version)] struct E { #[r_data] keys: Sidecar<Vec<i32>>, #[r_data(name = \"n.rows\")] r_rows: Sidecar<i32> }",
        )
        .unwrap();
        let out = super::derive_external_ptr(input, true).unwrap().to_string();
        assert!(
            out.contains("const REBUILDS_ANY_VERSION : bool = true ;"),
            "{out}"
        );
        // A save names its slots by the R names (#2215): `name = ..`, else
        // the ident. The visitor, which flushes, loads and lays out a
        // rebuild's slots, and every accessor pass the same name.
        assert!(
            out.contains(
                "const SIDECAR_NAMES : & 'static [& 'static str] = & [\"keys\" , \"n.rows\"] ;"
            ),
            "{out}"
        );
        assert!(
            out.contains("visit (1usize , \"n.rows\" , & self . r_rows) ;"),
            "{out}"
        );
        assert!(
            out.contains(
                "fn try_keys (saved : & :: miniextendr_api :: externalptr :: Saved < '_ , Self > ,)"
            ),
            "{out}"
        );
        // The getters keep the Rust names.
        assert!(out.contains("fn try_r_rows (saved"), "{out}");
        assert!(
            out.contains("sidecar_try_saved :: < Self , i32 > (saved , 1usize , \"n.rows\" ,)"),
            "{out}"
        );
        assert!(
            out.contains("sidecar_get :: < Self , i32 > (ptr , 1usize , \"n.rows\" ,"),
            "{out}"
        );
        assert!(
            out.contains("sidecar_set :: < Self , i32 > (ptr , 1usize , \"n.rows\" ,"),
            "{out}"
        );
        assert!(!out.contains("\"r_rows\""), "{out}");

        // Without a hook there is no `Saved` handle to read, so no `try_` getters.
        let input: syn::DeriveInput =
            syn::parse_str("struct E { #[r_data] keys: Sidecar<Vec<i32>> }").unwrap();
        let out = super::derive_external_ptr(input, true).unwrap().to_string();
        assert!(!out.contains("try_keys"), "{out}");
        assert!(!out.contains("REBUILDS"), "{out}");
    }

    /// `field_error(class = ...)` (#1899) and `restored(refuse =
    /// "every_read")` (#1901): parsed and checked, the classes reach the
    /// `TypedExternal` impl and the R helpers, and the opt-in emits the
    /// liveness check; without them the helpers are `NULL`.
    #[test]
    fn field_error_and_every_read_options() {
        let attrs = |source: &str| {
            let input: syn::DeriveInput = syn::parse_str(source).unwrap();
            super::parse_externalptr_attrs(&input)
        };
        let parsed = attrs(
            "#[externalptr(s3, field_error(class = [\"pkg_config\", \"pkg_error\"]), restored(class = \"pkg_saved\", refuse = \"every_read\"))] struct E;",
        )
        .unwrap();
        assert_eq!(parsed.field_error.class, ["pkg_config", "pkg_error"]);
        assert_eq!(parsed.field_error.message, None);
        assert!(parsed.restored.every_read);
        assert_eq!(parsed.restored.class, ["pkg_saved"]);
        let parsed = attrs("#[externalptr(field_error(class = \"pkg_error\"))] struct E;").unwrap();
        assert_eq!(parsed.field_error.class, ["pkg_error"]);
        // A message alone keeps miniextendr's classes (#1920).
        let parsed =
            attrs("#[externalptr(field_error(message = \"not a rec\"))] struct E;").unwrap();
        assert!(parsed.field_error.class.is_empty());
        assert_eq!(parsed.field_error.message.as_deref(), Some("not a rec"));
        assert!(!parsed.restored.every_read);
        // The no-field hint (#2112).
        let parsed =
            attrs("#[externalptr(field_error(no_field_hint = \"try `y$%s`\"))] struct E;").unwrap();
        assert_eq!(
            parsed.field_error.no_field_hint.as_deref(),
            Some("try `y$%s`")
        );
        assert_eq!(parsed.field_error.message, None);

        let refused = |source: &str, expected: &str| {
            let message = attrs(source)
                .err()
                .map(|e| e.to_string())
                .unwrap_or_else(|| panic!("`{source}` must be refused"));
            assert!(message.contains(expected), "`{source}`: {message}");
        };
        refused(
            "#[externalptr(restored(refuse = \"names\"))] struct E;",
            "`refuse` takes \"every_read\"",
        );
        refused(
            "#[externalptr(restored(refuse = \"every_read\", refuse = \"every_read\"))] struct E;",
            "given twice",
        );
        refused(
            "#[externalptr(field_error(class = []))] struct E;",
            "at least one",
        );
        refused(
            "#[externalptr(field_error(text = \"m\"))] struct E;",
            "unknown `field_error` option",
        );
        refused(
            "#[externalptr(field_error(message = \"\"))] struct E;",
            "`message` is empty",
        );
        refused(
            "#[externalptr(field_error(message = \"a\", message = \"b\"))] struct E;",
            "given twice",
        );
        refused(
            "#[externalptr(field_error(no_field_hint = \"\"))] struct E;",
            "`no_field_hint` is empty",
        );
        refused(
            "#[externalptr(field_error(no_field_hint = \"a\", no_field_hint = \"b\"))] struct E;",
            "given twice",
        );
        refused(
            "#[externalptr(field_error(class = \"a\"), field_error(class = \"b\"))] struct E;",
            "given twice",
        );

        let source = "#[externalptr(s3, field_error(class = [\"pkg_config\", \"pkg_error\"]), restored(refuse = \"every_read\"))] \
                      struct Engine { #[r_data] r: RSidecar, #[r_data] pub keys: Sidecar<Vec<i32>> }";
        let out = super::derive_external_ptr(syn::parse_str(source).unwrap(), true)
            .unwrap()
            .to_string();
        assert!(
            out.contains(
                "const FIELD_ERROR_CLASS : & 'static [& 'static str] = & [\"pkg_config\" , \"pkg_error\"] ;"
            ),
            "{out}"
        );
        let live = crate::naming::sidecar_live_c_name("Engine");
        assert!(out.contains(&format!("fn {live}")), "{out}");
        assert!(out.contains("sidecar_r_live :: < Engine >"), "{out}");
        assert!(
            out.contains(".rdata_error_class_Engine <- c(\\\"pkg_config\\\", \\\"pkg_error\\\")"),
            "{out}"
        );
        assert!(
            out.contains(&format!(
                ".rdata_live_Engine <- function(x, raise) .Call({live}, x, raise)"
            )),
            "{out}"
        );
        assert!(out.contains(".rdata_every_read_Engine <- TRUE"), "{out}");

        let out = super::derive_external_ptr(
            syn::parse_str(
                "struct Engine { #[r_data] r: RSidecar, #[r_data] pub keys: Sidecar<Vec<i32>> }",
            )
            .unwrap(),
            true,
        )
        .unwrap()
        .to_string();
        assert!(!out.contains("FIELD_ERROR_CLASS"), "{out}");
        assert!(!out.contains("mx_rdata_live_"), "{out}");
        assert!(out.contains(".rdata_error_class_Engine <- NULL"), "{out}");
        assert!(out.contains(".rdata_every_read_Engine <- FALSE"), "{out}");
        assert!(
            out.contains(".rdata_live_Engine <- function(x, raise) TRUE"),
            "{out}"
        );
    }

    /// The standalone accessors go to a `SidecarAccessorsEntry` in two
    /// renderings (#1900): exported on the type's page, and internal.
    #[test]
    fn standalone_accessors_come_exported_and_internal() {
        for exported in [true, false] {
            let out = generate_r_wrapper_for_slot(
                ClassSystem::S3,
                "T",
                "f",
                "get_f",
                Some("set_f"),
                true,
                exported,
            );
            assert!(out.contains("T_get_f <- function(x)"), "{out}");
            assert!(out.contains("T_set_f <- function(x, value)"), "{out}");
            assert_eq!(out.contains("@export"), exported, "{out}");
            assert_eq!(out.contains("@rdname T"), exported, "{out}");
            assert_eq!(
                out.matches("#' @noRd").count(),
                if exported { 0 } else { 2 },
                "{out}"
            );
        }
        let out = super::derive_external_ptr(
            syn::parse_str("struct T { #[r_data] r: RSidecar, #[r_data] pub f: i32 }").unwrap(),
            true,
        )
        .unwrap()
        .to_string();
        assert!(out.contains("MX_SIDECAR_ACCESSORS"), "{out}");
        assert!(out.contains("R_SIDECAR_ACCESSORS_T"), "{out}");
    }

    #[test]
    fn field_setter_visibility_reaches_standalone_and_integrated_wrappers() {
        for (attribute, explicit) in [
            ("", None),
            ("setter = \"visible\"", Some(false)),
            ("setter = \"invisible\"", Some(true)),
        ] {
            let input: syn::DeriveInput = syn::parse_str(&format!(
                "struct Example {{ #[r_data({attribute})] pub value: i32 }}"
            ))
            .unwrap();
            for system in ALL_CLASS_SYSTEMS {
                let info = super::parse_sidecar_info(&input, system).unwrap();
                let slot = &info.slots[0];
                assert_eq!(slot.setter_invisible, explicit);
                let standalone = generate_r_wrapper_for_slot(
                    system,
                    "Example",
                    "value",
                    "get_value",
                    Some("set_value"),
                    slot.setter_invisible.unwrap_or(true),
                    true,
                );
                assert_eq!(
                    standalone.contains("invisible(x)"),
                    explicit.unwrap_or(true)
                );
                assert!(standalone.contains(if explicit == Some(false) {
                    "pointer (visibly)"
                } else {
                    "pointer (invisibly)"
                }));
                let integrated = generate_class_integration_r_code(system, "Example", &[slot]);
                match system {
                    ClassSystem::R6 => assert_eq!(
                        integrated.contains("invisible(self)"),
                        explicit.unwrap_or(true)
                    ),
                    ClassSystem::S7 => assert_eq!(
                        integrated.contains("invisible(self)"),
                        explicit.unwrap_or(false)
                    ),
                    _ => assert!(integrated.is_empty()),
                }
            }
        }
    }

    #[test]
    fn setter_visibility_and_property_docs_can_share_or_split_attributes() {
        for attrs in [
            "#[r_data(prop_doc = \"A counter\", setter = \"visible\")]",
            "#[r_data] #[r_data(setter = \"visible\", prop_doc = \"A counter\")]",
        ] {
            let input: syn::DeriveInput =
                syn::parse_str(&format!("struct Example {{ {attrs} pub value: i32 }}")).unwrap();
            let info = super::parse_sidecar_info(&input, ClassSystem::S7).unwrap();
            assert_eq!(info.slots[0].prop_doc.as_deref(), Some("A counter"));
            assert_eq!(info.slots[0].setter_invisible, Some(false));
        }
    }

    /// `Sidecar` fields count among themselves: the scalars and conversion
    /// fields between them take no protection-list position. The derive
    /// emits the count, the visitor hook, and typed accessors on the handle
    /// with each field's visibility; the R accessors read and write the
    /// protection list by index.
    #[test]
    fn sidecar_fields_number_their_own_positions() {
        let input: syn::DeriveInput = syn::parse_str(
            "struct Engine { #[r_data] _r: RSidecar, #[r_data] pub a: i32, \
             #[r_data] pub keys: Sidecar<Vec<i32>>, #[r_data] pub c: String, \
             #[r_data] steps: Sidecar<Option<List>> }",
        )
        .unwrap();
        let info = super::parse_sidecar_info(&input, ClassSystem::Env).unwrap();
        let kinds: Vec<_> = info.slots.iter().map(|slot| slot.kind.clone()).collect();
        assert_eq!(
            kinds,
            [
                super::SlotKind::ScalarInt,
                super::SlotKind::Sidecar(0),
                super::SlotKind::Conversion,
                super::SlotKind::Sidecar(1),
            ]
        );
        // A bare `#[r_data]` means `ref, mut`.
        assert_eq!(
            info.slots[1].access,
            super::SidecarAccess {
                get: true,
                set: true
            }
        );

        let out = super::derive_external_ptr(input, true).unwrap().to_string();
        assert!(
            out.contains("const R_SLOT_COUNT : usize = 2usize ;"),
            "{out}"
        );
        assert!(
            out.contains("visit (0usize , \"keys\" , & self . keys) ; visit (1usize , \"steps\" , & self . steps) ;"),
            "{out}"
        );
        // The accessors are associated functions taking the handle, not
        // methods on the struct (#1856).
        assert!(
            out.contains(
                "pub fn keys (ptr : & impl :: miniextendr_api :: externalptr :: SidecarOwner < Self >) -> Vec < i32 > { :: miniextendr_api :: externalptr :: sidecar_get :: < Self , Vec < i32 > > (ptr , 0usize , \"keys\" , | this : & Self | & this . keys ,) }"
            ),
            "{out}"
        );
        assert!(
            out.contains(
                "pub fn set_keys (ptr : & mut impl :: miniextendr_api :: externalptr :: SidecarOwnerMut < Self > , value : Vec < i32 >) { :: miniextendr_api :: externalptr :: sidecar_set :: < Self , Vec < i32 > > (ptr , 0usize , \"keys\" , | this : & Self | & this . keys , value ,) }"
            ),
            "{out}"
        );
        assert!(!out.contains("fn keys (& self)"), "{out}");
        // A private field gets private accessors (allowed to be unused) and
        // no R accessor.
        assert!(
            out.contains(
                "# [allow (dead_code)] fn steps (ptr : & impl :: miniextendr_api :: externalptr :: SidecarOwner < Self >) -> Option < List >"
            ),
            "{out}"
        );
        assert!(
            out.contains(
                "# [allow (dead_code)] fn set_steps (ptr : & mut impl :: miniextendr_api :: externalptr :: SidecarOwnerMut < Self > , value : Option < List >)"
            ),
            "{out}"
        );
        assert!(out.contains("(ptr , 1usize , \"steps\" ,"), "{out}");
        assert!(!out.contains("get_steps"), "{out}");

        // The R accessors read and write the protection list, not the struct.
        let keys = &info.slots[1];
        let name = syn::Ident::new("Engine", proc_macro2::Span::call_site());
        let getter = super::generate_getter_body(&name, keys).to_string();
        // The `require_live` flag of the `.Call()` decides whether a restored
        // pointer is read or refused (#1891).
        assert!(
            getter.contains(
                "sidecar_r_get :: < Engine > (x , 0usize , :: miniextendr_api :: externalptr :: sidecar_require_live (require_live) ,)"
            ),
            "{getter}"
        );
        assert!(!getter.contains("R_ExternalPtrAddr"), "{getter}");
        let setter = super::generate_setter_body(&name, keys).to_string();
        assert!(
            setter.contains("sidecar_r_check :: < Engine > (x , require_live)"),
            "{setter}"
        );
        // The value is validated as the field's `T` and reported as it.
        assert!(
            setter.contains("< Vec < i32 > as TryFromSexp > :: try_from_sexp (value)"),
            "{setter}"
        );
        assert!(setter.contains("\"'keys' must be integer\""), "{setter}");
        assert!(setter.contains("Some (\"Vec<i32>\")"), "{setter}");
        assert!(
            setter.contains("sidecar_r_set :: < Engine > (x , 0usize , value , require_live ,)"),
            "{setter}"
        );
    }

    /// `ref` generates only the getter, `mut` only the setter.
    #[test]
    fn sidecar_access_options_select_the_accessors() {
        let input: syn::DeriveInput = syn::parse_str(
            "struct Engine { #[r_data(ref)] pub keys: Sidecar<Vec<i32>>, \
             #[r_data(mut)] pub(crate) note: Sidecar<String> }",
        )
        .unwrap();
        let info = super::parse_sidecar_info(&input, ClassSystem::Env).unwrap();
        assert_eq!(
            info.slots[0].access,
            super::SidecarAccess {
                get: true,
                set: false
            }
        );
        assert_eq!(
            info.slots[1].access,
            super::SidecarAccess {
                get: false,
                set: true
            }
        );
        let out = super::derive_external_ptr(input, true).unwrap().to_string();
        assert!(
            out.contains(
                "pub fn keys (ptr : & impl :: miniextendr_api :: externalptr :: SidecarOwner < Self >) -> Vec < i32 >"
            ),
            "{out}"
        );
        assert!(!out.contains("fn set_keys"), "{out}");
        assert!(
            out.contains(
                "# [allow (dead_code)] pub (crate) fn set_note (ptr : & mut impl :: miniextendr_api :: externalptr :: SidecarOwnerMut < Self > , value : String)"
            ),
            "{out}"
        );
        assert!(!out.contains("fn note ("), "{out}");
        // Both options together, in either order, and the hook still lists
        // every field.
        let input: syn::DeriveInput =
            syn::parse_str("struct Engine { #[r_data(mut, ref)] pub keys: Sidecar<Vec<i32>> }")
                .unwrap();
        let info = super::parse_sidecar_info(&input, ClassSystem::Env).unwrap();
        assert_eq!(
            info.slots[0].access,
            super::SidecarAccess {
                get: true,
                set: true
            }
        );
    }

    /// `ref` / `mut` are refused on a plain struct field, a `Sidecar` field
    /// needs `#[r_data]`, and a duplicate option is an error.
    #[test]
    fn sidecar_access_options_are_checked() {
        let refused = |source: &str| {
            let input: syn::DeriveInput = syn::parse_str(source).unwrap();
            super::parse_sidecar_info(&input, ClassSystem::Env)
                .err()
                .map(|err| err.to_string())
                .unwrap_or_else(|| panic!("`{source}` must be refused"))
        };
        let message = refused("struct E { #[r_data(ref)] pub count: i32 }");
        assert!(
            message.contains("apply to `Sidecar<T>` fields only"),
            "{message}"
        );
        let message = refused("struct E { pub keys: Sidecar<Vec<i32>> }");
        assert!(message.contains("needs `#[r_data]`"), "{message}");
        let message = refused("struct E { #[r_data(ref, ref)] pub keys: Sidecar<Vec<i32>> }");
        assert!(message.contains("duplicate `ref`"), "{message}");
        let message = refused("struct E { #[r_data] pub keys: Sidecar }");
        assert!(message.contains("takes one type argument"), "{message}");
    }

    /// A struct without `Sidecar` fields keeps the trait's default count and
    /// hook, and gets no accessors.
    /// The helpers of the S3 / S4 / env field methods (#1848): the field
    /// names, getter and setter `switch()`es over the accessors' C symbols
    /// (a raw identifier's R name backtick-quoted), and the classed error.
    #[test]
    fn field_syntax_helpers_switch_over_the_accessors() {
        let slot = |name: &str| super::SidecarSlot {
            name: syn::parse_str(name).unwrap(),
            r_name: crate::naming::ident_name(&syn::parse_str::<syn::Ident>(name).unwrap()),
            ty: syn::parse_quote!(i32),
            vis: syn::parse_quote!(pub),
            is_public: true,
            kind: super::SlotKind::ScalarInt,
            access: super::SidecarAccess::default(),
            prop_doc: None,
            setter_invisible: None,
        };
        let (keys, reserved) = (slot("keys"), slot("r#for"));
        let out =
            super::generate_field_syntax_helpers("Engine", &[&keys, &reserved], &[], None, false);
        assert!(
            out.contains(".rdata_fields_Engine <- c(\"keys\", \"for\")\n"),
            "{out}"
        );
        let getter = crate::naming::sidecar_getter_c_name("Engine", "keys");
        let setter = crate::naming::sidecar_setter_c_name("Engine", "for");
        assert!(
            out.contains(&format!(
                ".rdata_get_Engine <- function(x, name) switch(name,\n  keys = .Call({getter}, x, TRUE),"
            )),
            "{out}"
        );
        assert!(
            out.contains(&format!("  `for` = .Call({setter}, x, value, TRUE))\n")),
            "{out}"
        );
        assert!(
            out.contains(
                "function(name, env, cls) stop(errorCondition(\n  sprintf(\"`%s` is not a field of `%s`; its fields are `keys`, `for`\", name, cls),"
            ),
            "{out}"
        );
        assert!(
            out.contains("class = c(.rdata_error_class_Engine, \"miniextendr_no_field\"), call = .miniextendr_frame_call(env)"),
            "{out}"
        );

        // `no_field_hint` (#2112): the hint follows the field list, each `%s`
        // the name asked for; any other `%`, a quote or a backslash in it is
        // written as given.
        let out = super::generate_field_syntax_helpers(
            "Engine",
            &[&keys],
            &[],
            Some("See `t$%s` or \"u\\%s\" (50% off)."),
            false,
        );
        assert!(
            out.contains(
                "  paste0(sprintf(\"`%s` is not a field of `%s`; its fields are `keys`\", name, cls), \". \", \
                 \"See `t$\", name, \"` or \\\"u\\\\\", name, \"\\\" (50% off).\"),\n"
            ),
            "{out}"
        );
    }

    /// The helpers come with the R accessors, whatever the class system; a
    /// type without them gets none.
    #[test]
    fn field_syntax_helpers_follow_the_r_accessors() {
        for attr in ["", "#[externalptr(r6)]", "#[externalptr(s3)]"] {
            let input: syn::DeriveInput = syn::parse_str(&format!(
                "{attr} struct Engine {{ #[r_data] _r: RSidecar, #[r_data] pub count: i32 }}"
            ))
            .unwrap();
            let out = super::derive_external_ptr(input, true).unwrap().to_string();
            assert!(out.contains(".rdata_fields_Engine"), "{attr}: {out}");
        }
        let input: syn::DeriveInput =
            syn::parse_str("struct Engine { #[r_data] pub count: i32 }").unwrap();
        let out = super::derive_external_ptr(input, true).unwrap().to_string();
        assert!(!out.contains(".rdata_"), "{out}");
    }

    #[test]
    fn no_sidecar_fields_emit_no_count_or_hook() {
        let input: syn::DeriveInput =
            syn::parse_str("struct Plain { #[r_data] _r: RSidecar, #[r_data] pub a: i32 }")
                .unwrap();
        let out = super::derive_external_ptr(input, true).unwrap().to_string();
        assert!(!out.contains("R_SLOT_COUNT"), "{out}");
        assert!(!out.contains("__mx_visit_sidecars"), "{out}");
        assert!(!out.contains("sidecar_get"), "{out}");
    }

    #[test]
    fn r_views_in_plain_fields_are_refused_recursively() {
        for ty in [
            "List",
            "ListMut",
            "NamedList",
            "DataFrame",
            "StrVec<'static>",
            "RCow<'static, i32>",
            "RArray<i32, 2>",
            "RVector<f64>",
            "RMatrix<i32>",
            "RArray3D<f64>",
            "Factor<'static>",
            "FactorMut<'static>",
            "::miniextendr_api::list::List",
            "Option<List>",
            "Vec<Option<DataFrame>>",
            "HashMap<String, Vec<List>>",
            "Result<Vec<i32>, SEXP>",
            "Box<[List]>",
            "[Option<List>; 2]",
            "(i32, Vec<NamedList>)",
            "&'static List",
            "&'static str",
            "Option<&'static i32>",
            "Box<&'static [f64]>",
            "Arc<Mutex<Option<List>>>",
            "(List)",
        ] {
            let input =
                syn::parse_str(&format!("struct Bad {{ #[r_data] pub value: {ty} }}")).unwrap();
            let err = super::derive_external_ptr(input, true).unwrap_err();
            assert!(err.to_string().contains("is not rooted"), "{ty}: {err}");
            assert!(err.to_string().contains("Sidecar<"), "{ty}: {err}");
        }
    }

    #[test]
    fn owned_fields_and_sidecars_keep_their_existing_classification() {
        for ty in [
            "String",
            "Vec<Option<i32>>",
            "HashMap<String, Vec<f64>>",
            "Preserved",
            "BuiltList",
            "BuiltDataFrame",
            "ProtectedStrVec",
            "Option<BuiltList>",
            "Cow<'static, str>",
            "PhantomData<List>",
        ] {
            let ty = syn::parse_str(ty).unwrap();
            assert!(!super::contains_unrooted_r_view(&ty), "{ty:?}");
        }
        for ty in [
            "Sidecar<List>",
            "Sidecar<Option<List>>",
            "Sidecar<DataFrame>",
        ] {
            let ty = syn::parse_str(ty).unwrap();
            let kind = super::slot_kind_for_type(&ty, 2, None, &syn::parse_quote!(Host)).unwrap();
            assert!(matches!(kind, super::SlotKind::Sidecar(2)));
        }
    }

    /// A bare `SEXP` under `#[r_data]` is refused: nothing would root it.
    #[test]
    fn bare_sexp_sidecar_field_is_refused() {
        let input: syn::DeriveInput =
            syn::parse_str("struct Engine { #[r_data] _r: RSidecar, #[r_data] pub keys: SEXP }")
                .unwrap();
        let Err(err) = super::parse_sidecar_info(&input, ClassSystem::Env) else {
            panic!("a SEXP sidecar field must be refused");
        };
        let message = err.to_string();
        assert!(message.contains("is not rooted"), "{message}");
        assert!(
            message.contains("Declare the field as `Sidecar<SEXP>`"),
            "{message}"
        );
    }
}