miniextendr_macros/

altrep_derive.rs

//! Derive macros for ALTREP data traits.
//!
//! These macros auto-implement `AltrepLen` and `Alt*Data` traits for simple field-based
//! ALTREP types, reducing boilerplate for users.
//!
//! # Two paths: field-based vs manual
//!
//! `#[derive(AltrepInteger)]` (and the `Real` / `Logical` / `Raw` / `String`
//! / `Complex` / `List` variants) drive one of two code paths:
//!
//! 1. **Field-based** *(default)* — point the derive at struct fields that
//!    hold the vector length and a constant element value:
//!
//!    ```ignore
//!    #[derive(AltrepInteger)]
//!    #[altrep(len = "n", elt = "value", class = "Repeat")]
//!    struct Repeat { n: usize, value: i32 }
//!    ```
//!
//!    The derive emits `AltrepLen`, `AltIntegerData`, `Altrep`, `AltVec`,
//!    `RegisterAltrep`, and the `R_make_altinteger_class` registration. No
//!    extra trait impls required.
//!
//! 2. **Manual** — `#[altrep(manual)]` suppresses `AltrepLen` /
//!    `AltIntegerData` generation so you can write the element-access logic
//!    yourself. The low-level trait impls (`Altrep`, `AltVec`, family
//!    methods, `InferBase`) are still emitted — `#[altrep(no_lowlevel)]` is
//!    the additional escape hatch when you also want to control `Altrep` /
//!    `AltVec` directly.
//!
//! Pick by what your data looks like: a finite buffer that fits in a struct
//! field → field-based; a computed element (`fibonacci(i)`) → manual.
//!
//! # Guard mode attribute
//!
//! The derive recognises `#[altrep(unsafe)]` / `#[altrep(rust_unwind)]` /
//! `#[altrep(r_unwind)]` on the struct, which sets the runtime
//! `Altrep::GUARD` const that the trampolines in `altrep_bridge` dispatch
//! on. Default is `r_unwind` (safe for callbacks that call R APIs).
//!
//! # Derive validation rules
//!
//! Several `#[altrep(...)]` options conflict; the derive rejects illegal
//! combinations at compile time:
//!
//! | Option | Allowed on families | Conflicts with |
//! |---|---|---|
//! | `subset` | all atomic (integer, real, logical, raw, string, complex) | `dataptr`, `list` |
//! | `dataptr` | integer, real, logical, raw, string, complex | `subset`, `list` |
//! | `serialize` | all | (none) |
//! | `manual` | all | (none — turns off `AltrepLen`/`Alt*Data` generation) |
//! | `no_lowlevel` | all | (none — also suppresses the low-level trait impls) |
//!
//! The list family rejects `dataptr` and `subset` — list elements are
//! arbitrary SEXPs, so there is no contiguous buffer to expose.

use proc_macro2::TokenStream;
use quote::quote;
use syn::spanned::Spanned;

/// Per-family configuration controlling low-level code generation for an ALTREP type family.
///
/// Each ALTREP family (integer, real, logical, raw, string, complex, list) has a distinct
/// set of runtime macros for trait implementations and different capabilities (e.g., only
/// some families support `dataptr` or `subset`). This struct captures those differences
/// so [`AltrepAttrs::generate_lowlevel`] can emit the correct code.
struct AltrepFamilyConfig<'a> {
    /// Human-readable family name used in option-validation error messages
    /// (e.g., `"AltrepInteger"`).
    family_name: &'a str,
    /// If this family supports a typed `dataptr` materialization macro, the tuple contains:
    /// - The macro name (e.g., `"__impl_altvec_dataptr"`)
    /// - An optional element type token stream (e.g., `i32` for integer, `f64` for real)
    ///
    /// `None` means this family does not have a typed dataptr macro (e.g., list).
    dataptr_macro: Option<(&'a str, Option<TokenStream>)>,
    /// Whether this family supports the string-specific dataptr materialization macro
    /// (`__impl_altvec_string_dataptr`). Only `true` for the String family.
    string_dataptr: bool,
    /// Whether this family supports the `subset` option for `Extract_subset` method
    /// registration. `false` for List (which rejects `subset` and `dataptr`).
    subset: bool,
    /// Name of the internal macro for type-specific method implementations
    /// (e.g., `"__impl_altinteger_methods"` for integer).
    methods_macro: &'a str,
    /// Name of the `impl_inferbase_*!` macro that provides `InferBase` for this family
    /// (e.g., `"impl_inferbase_integer"`).
    inferbase_macro: &'a str,
    /// Default guard mode for this family when no explicit guard is specified.
    /// String family uses `RUnwind` because elt/dataptr call R APIs (Rf_mkCharLenCE).
    /// All families now default to `RUnwind`.
    default_guard: &'a str,
    /// Family-specific materializing dataptr macro (e.g.
    /// `"__impl_altvec_integer_dataptr"`). The default/serialize arms use it
    /// to install the trivial `AltrepDataptr` + materializing `AltVec`.
    materializing_dataptr_macro: &'a str,
}

/// Parsed `#[altrep(...)]` attributes controlling ALTREP derive code generation.
///
/// These attributes are placed on the struct and parsed by all ALTREP derive macros
/// (`AltrepInteger`, `AltrepReal`, etc.) to customize the generated trait implementations.
///
/// # Supported `#[altrep(...)]` keys
///
/// | Key | Type | Description |
/// |-----|------|-------------|
/// | `len = "field"` | `String` | Name of the struct field that holds the vector length. Auto-detected if a field is named `len` or `length`. |
/// | `elt = "field"` | `String` | Name of the struct field to return as the element value (produces a constant-value vector). If omitted, the default `elt()` returns `NA` / `NaN` / `0` / `None` depending on the family. |
/// | `manual` | Flag | Skip automatic `AltrepLen` and `Alt*Data` trait generation. Use when you want to write those trait impls by hand (e.g., for custom `elt` logic, `no_na`, `sum`, etc.). The low-level trait impls (`Altrep`, `AltVec`, family methods, `InferBase`) are still emitted automatically — you do **not** need to write them yourself. Use `no_lowlevel` as an additional escape hatch if you also want to suppress those. |
/// | `no_lowlevel` | Flag | Suppress the automatic low-level trait impls. Use this when you want to provide your own `Altrep`, `AltVec`, and family-specific trait implementations. |
/// | `dataptr` | Flag | Enable `Dataptr` method registration, allowing R to get a direct pointer to the underlying data. Mutually exclusive with `subset`. Not supported for List. |
/// | `serialize` | Flag | Enable `Serialized_state` and `Unserialize` method registration for ALTREP serialization support. |
/// | `duplicate = "clone"` | String | Keep ALTREP on duplication: clone the owner (requires `Clone`) and copy the R cache. Omission retains R's default, which materializes an ordinary vector. |
/// | `subset` | Flag | Enable `Extract_subset` method registration. Mutually exclusive with `dataptr`. Supported on all atomic families. Not supported for List. |
/// | `unsafe` | Flag | Set native-read guard to `Unsafe` -- no panic protection. Allocating bridges stay protected. |
/// | `rust_unwind` | Flag | Set native-read guard to `RustUnwind` -- `catch_unwind` only; reads must not call fallible R APIs. |
/// | `r_unwind` | Flag | Set guard mode to `RUnwind` (default) -- uses `with_r_unwind_protect` for safe R API calls. |
/// | `class = "name"` | `String` | Override the ALTREP class name (default: struct name). |
struct AltrepAttrs {
    /// Field name containing the vector length, set via `#[altrep(len = "field")]`.
    /// If `None`, auto-detection looks for fields named `len` or `length`.
    len_field: Option<syn::Ident>,
    /// Field name for constant-value element access, set via `#[altrep(elt = "field")]`.
    /// When set, `elt()` returns `self.{field}` for every index.
    elt_field: Option<syn::Ident>,
    /// Field name for delegated element access, set via `#[altrep(elt_delegate = "field")]`.
    /// When set, `elt()` calls `self.{field}.elt(i)`, delegating to the inner type's
    /// `AltIntegerData`/`AltRealData`/etc. implementation. Useful for wrapper types
    /// around `StreamingIntData`, `StreamingRealData`, etc.
    elt_delegate: Option<syn::Ident>,
    /// Whether to generate the low-level trait impls (`Altrep`, `AltVec`,
    /// family methods, `InferBase`). Defaults to `true`. Set to `false` by
    /// `#[altrep(no_lowlevel)]`.
    generate_lowlevel: bool,
    /// Collected option flags (`dataptr`, `serialize`, `subset`) passed to the runtime macro.
    lowlevel_options: Vec<syn::Ident>,
    /// Guard mode override for ALTREP trampoline callbacks. Maps to `AltrepGuard` variants:
    /// - `Unsafe` -- no protection
    /// - `RustUnwind` -- `catch_unwind` only
    /// - `RUnwind` -- `with_r_unwind_protect` (default)
    guard: Option<syn::Ident>,
    /// Override the ALTREP class name. Default: struct name.
    class_name: Option<String>,
    /// Manual mode: skip `AltrepLen` and `Alt*Data` generation. User provides their own.
    /// Set by `#[altrep(manual)]`. Lowlevel traits + registration still generated.
    manual: bool,
    /// Opt-in duplicate policy; absent retains R's materializing default.
    duplicate: Option<syn::LitStr>,
}

impl AltrepAttrs {
    /// Parses all `#[altrep(...)]` attributes from a derive input struct.
    ///
    /// Multiple `#[altrep(...)]` attributes are supported and their contents are merged.
    /// Unknown keys produce a compile error.
    ///
    /// # Errors
    ///
    /// Returns `Err` if an `#[altrep(...)]` attribute has malformed syntax or contains
    /// an unknown key.
    fn parse(input: &syn::DeriveInput) -> syn::Result<Self> {
        let mut len_field = None;
        let mut elt_field = None;
        let mut elt_delegate = None;
        let mut generate_lowlevel = true; // Default: generate
        let mut lowlevel_options = Vec::new();
        let mut guard = None;
        let mut class_name = None;
        let mut manual = false;
        let mut duplicate = None;

        for attr in &input.attrs {
            if !attr.path().is_ident("altrep") {
                continue;
            }

            attr.parse_nested_meta(|meta| {
                if meta.path.is_ident("len") {
                    let _: syn::Token![=] = meta.input.parse()?;
                    let field: syn::LitStr = meta.input.parse()?;
                    len_field = Some(syn::Ident::new(&field.value(), field.span()));
                } else if meta.path.is_ident("elt") {
                    let _: syn::Token![=] = meta.input.parse()?;
                    let field: syn::LitStr = meta.input.parse()?;
                    elt_field = Some(syn::Ident::new(&field.value(), field.span()));
                } else if meta.path.is_ident("elt_delegate") {
                    let _: syn::Token![=] = meta.input.parse()?;
                    let field: syn::LitStr = meta.input.parse()?;
                    elt_delegate = Some(syn::Ident::new(&field.value(), field.span()));
                } else if meta.path.is_ident("duplicate") {
                    if duplicate.is_some() {
                        return Err(meta.error("duplicate `duplicate` policy"));
                    }
                    let policy: syn::LitStr = meta.value()?.parse()?;
                    if policy.value() != "clone" {
                        return Err(syn::Error::new(
                            policy.span(),
                            "duplicate policy must be `clone`",
                        ));
                    }
                    duplicate = Some(policy);
                } else if meta.path.is_ident("no_lowlevel") {
                    generate_lowlevel = false;
                } else if meta.path.is_ident("manual") {
                    manual = true;
                } else if meta.path.is_ident("class") {
                    let _: syn::Token![=] = meta.input.parse()?;
                    let name: syn::LitStr = meta.input.parse()?;
                    class_name = Some(name.value());
                } else if meta.path.is_ident("dataptr") {
                    lowlevel_options.push(syn::Ident::new("dataptr", meta.path.span()));
                } else if meta.path.is_ident("serialize") {
                    lowlevel_options.push(syn::Ident::new("serialize", meta.path.span()));
                } else if meta.path.is_ident("subset") {
                    lowlevel_options.push(syn::Ident::new("subset", meta.path.span()));
                } else if meta.path.is_ident("r#unsafe") || meta.path.is_ident("unsafe") {
                    guard = Some(syn::Ident::new("Unsafe", meta.path.span()));
                } else if meta.path.is_ident("rust_unwind") {
                    guard = Some(syn::Ident::new("RustUnwind", meta.path.span()));
                } else if meta.path.is_ident("r_unwind") {
                    guard = Some(syn::Ident::new("RUnwind", meta.path.span()));
                } else {
                    return Err(meta.error(
                        "unknown #[altrep(...)] attribute; expected one of: \
                         `len`, `elt`, `elt_delegate`, `manual`, `no_lowlevel`, `class`, \
                         `dataptr`, `serialize`, `subset`, `duplicate`, `unsafe`, \
                         `rust_unwind`, `r_unwind`",
                    ));
                }
                Ok(())
            })?;
        }

        if !generate_lowlevel && let Some(policy) = &duplicate {
            return Err(syn::Error::new(
                policy.span(),
                "`duplicate` requires generated low-level traits; remove `no_lowlevel`",
            ));
        }
        Ok(Self {
            len_field,
            elt_field,
            elt_delegate,
            generate_lowlevel,
            lowlevel_options,
            guard,
            class_name,
            manual,
            duplicate,
        })
    }

    /// Extra methods in the existing base impl; R's DuplicateEX still copies
    /// attributes and object flags around this Duplicate hook.
    fn duplicate_methods(&self) -> TokenStream {
        if self.duplicate.is_none() {
            return quote! {};
        }
        quote! {
            , extra = {
                const HAS_DUPLICATE: bool = true;
                fn duplicate(x: ::miniextendr_api::SEXP, _deep: bool) -> ::miniextendr_api::SEXP {
                    unsafe { ::miniextendr_api::altrep_impl::duplicate_altrep_owner::<Self>(x) }
                }
            }
        }
    }

    /// Returns the length field identifier, either from the explicit `len = "..."` attribute
    /// or by auto-detecting a field named `len` or `length` on the struct.
    ///
    /// # Errors
    ///
    /// Returns `Err` if the input is not a struct, or if no length field was specified
    /// and auto-detection fails.
    fn get_len_field(&self, input: &syn::DeriveInput) -> syn::Result<syn::Ident> {
        if let Some(ref field) = self.len_field {
            return Ok(field.clone());
        }

        // Try to auto-detect: look for field named "len" or "length"
        let fields = match &input.data {
            syn::Data::Struct(data_struct) => &data_struct.fields,
            _ => {
                return Err(syn::Error::new(
                    input.span(),
                    "Altrep derive only supports structs",
                ));
            }
        };

        for field in fields {
            if let Some(ident) = &field.ident
                && (ident == "len" || ident == "length")
            {
                return Ok(ident.clone());
            }
        }

        Err(syn::Error::new(
            input.span(),
            "no length field found; specify with #[altrep(len = \"field_name\")]",
        ))
    }

    /// Validates that the requested `#[altrep(...)]` option flags are compatible with
    /// the given ALTREP type family.
    ///
    /// Enforces two rules:
    /// 1. `subset` is only valid for families where `supports_subset` is `true`.
    /// 2. `dataptr` and `subset` are mutually exclusive.
    ///
    /// # Arguments
    ///
    /// * `family` -- A human-readable family name used in error messages (e.g., `"AltrepList"`).
    /// * `supports_subset` -- Whether this family supports the `Extract_subset` method.
    ///
    /// # Errors
    ///
    /// Returns `Err` with a span pointing to the offending option identifier.
    fn validate_options(&self, family: &str, supports_subset: bool) -> syn::Result<()> {
        let has_dataptr = self.lowlevel_options.iter().any(|o| o == "dataptr");
        let has_subset = self.lowlevel_options.iter().any(|o| o == "subset");

        if has_subset && !supports_subset {
            return Err(syn::Error::new(
                self.lowlevel_options
                    .iter()
                    .find(|o| *o == "subset")
                    .unwrap()
                    .span(),
                format!("`subset` is not supported for {family}"),
            ));
        }

        if has_dataptr && has_subset {
            return Err(syn::Error::new(
                self.lowlevel_options
                    .iter()
                    .find(|o| *o == "subset")
                    .unwrap()
                    .span(),
                "`dataptr` and `subset` are mutually exclusive",
            ));
        }

        Ok(())
    }

    /// Generates low-level ALTREP trait implementation code for a given type family.
    ///
    /// Emits the underlying trait-impl macros directly (Path (a) from #682,
    /// landed via #711/#933), reproducing the `impl_alt<family>_from_data!`
    /// arm expansions from the proc-macro with no declarative-macro hop. The
    /// four items every arm produces are:
    ///
    /// 1. `__impl_altrep_base!(Ty, <guard>[, with_serialize])` — `impl Altrep`.
    /// 2. an `AltVec` impl, one of:
    ///    - materializing (`materializing_dataptr_macro`) — default/serialize arms,
    ///    - direct dataptr (`__impl_altvec_dataptr!(Ty, <elem>)`; string routes
    ///      through `__impl_altvec_string_dataptr!`) — `dataptr` arm,
    ///    - subset (`__impl_altvec_extract_subset!`) — `subset` arm,
    /// 3. `methods_macro!(Ty)` — the family `Alt<Family>` impl,
    /// 4. `inferbase_macro!(Ty)` — `impl InferBase`.
    ///
    /// The guard is honoured uniformly (the retired declarative-macro
    /// delegation only handled the default `RUnwind` guard; non-default guards
    /// used a separate expanded path) and option combinations are validated
    /// here at the derive call site rather than 7 hops deep in macro
    /// expansion.
    ///
    /// # Arguments
    ///
    /// * `name` -- The struct identifier.
    /// * `family` -- The family-specific configuration controlling which macros to emit.
    ///
    /// # Returns
    ///
    /// A token stream containing the macro invocations, or an empty stream if
    /// `no_lowlevel` was specified.
    ///
    /// # Errors
    ///
    /// Returns `Err` if option validation fails (e.g., `subset` on an
    /// unsupported family, or `dataptr` combined with `subset`).
    fn generate_lowlevel(
        &self,
        name: &syn::Ident,
        generics: &syn::Generics,
        family: &AltrepFamilyConfig,
    ) -> syn::Result<TokenStream> {
        let (_, ty_generics, _) = generics.split_for_impl();
        let AltrepFamilyConfig {
            family_name,
            ref dataptr_macro,
            string_dataptr,
            subset,
            methods_macro,
            inferbase_macro,
            default_guard,
            materializing_dataptr_macro,
        } = *family;

        if !self.generate_lowlevel {
            return Ok(quote! {});
        }

        self.validate_options(family_name, subset)?;

        let has_serialize = self.lowlevel_options.iter().any(|o| o == "serialize");
        let has_dataptr = self.lowlevel_options.iter().any(|o| o == "dataptr");
        let has_subset = self.lowlevel_options.iter().any(|o| o == "subset");

        let guard = self
            .guard
            .as_ref()
            .cloned()
            .unwrap_or_else(|| syn::Ident::new(default_guard, proc_macro2::Span::call_site()));

        // 1. Altrep base. The declarative macro's default/dataptr/subset arms use
        //    `__impl_altrep_base!($ty)` (default RUnwind guard); the `*serialize`
        //    arms use `__impl_altrep_base!($ty, with_serialize)`. We additionally
        //    thread an explicit guard so non-default guards no longer need a
        //    separate code path.
        let duplicate = self.duplicate_methods();
        let base_impl = if has_serialize {
            quote! { ::miniextendr_api::__impl_altrep_base!(#name #ty_generics, #guard, with_serialize #duplicate); }
        } else {
            quote! { ::miniextendr_api::__impl_altrep_base!(#name #ty_generics, #guard #duplicate); }
        };

        // 2. AltVec impl. Mirrors the per-arm choice in `impl_alt<family>_from_data!`:
        //    - `dataptr` arm -> direct `__impl_altvec_dataptr!($ty, $elem)`; the
        //      string family has no typed contiguous pointer, so its `dataptr`
        //      arm routes through `__impl_altvec_string_dataptr!` (whole-vector
        //      STRSXP materialization — same emission as its default arm),
        //    - `subset` arm  -> `__impl_altvec_extract_subset!`,
        //    - default / serialize arms -> the family materializing dataptr macro
        //      (e.g. `__impl_altvec_integer_dataptr!`), which installs a trivial
        //      `AltrepDataptr` returning `None` then delegates to
        //      `__impl_altvec_dataptr!`.
        let vec_impl = if has_dataptr {
            if string_dataptr {
                quote! { ::miniextendr_api::__impl_altvec_string_dataptr!(#name #ty_generics); }
            } else {
                let (macro_name, elem_ty) = dataptr_macro
                    .as_ref()
                    .expect("emit_direct family must define a typed dataptr macro");
                let dp_macro = syn::Ident::new(macro_name, proc_macro2::Span::call_site());
                let elem = elem_ty
                    .as_ref()
                    .expect("emit_direct dataptr macro must carry an element type");
                quote! { ::miniextendr_api::#dp_macro!(#name #ty_generics, #elem); }
            }
        } else if has_subset {
            quote! { ::miniextendr_api::__impl_altvec_extract_subset!(#name #ty_generics); }
        } else {
            let mat_macro =
                syn::Ident::new(materializing_dataptr_macro, proc_macro2::Span::call_site());
            quote! { ::miniextendr_api::#mat_macro!(#name #ty_generics); }
        };

        // 3. Family method impl (`impl Alt<Family>`).
        let methods_ident = syn::Ident::new(methods_macro, proc_macro2::Span::call_site());
        let methods_impl = quote! { ::miniextendr_api::#methods_ident!(#name #ty_generics); };

        // 4. InferBase.
        let inferbase_ident = syn::Ident::new(inferbase_macro, proc_macro2::Span::call_site());
        let inferbase_impl = quote! { ::miniextendr_api::#inferbase_ident!(#name #ty_generics); };

        Ok(quote! {
            #base_impl
            #vec_impl
            #methods_impl
            #inferbase_impl
        })
    }
}

/// Generates an `impl AltrepLen for T` block that delegates to a named struct field.
///
/// The generated implementation returns `self.{len_field}` cast to `usize` as the
/// ALTREP vector length.
///
/// # Arguments
///
/// * `name` -- The struct identifier.
/// * `generics` -- Generic parameters for the struct.
/// * `len_field` -- The identifier of the field that holds the length value.
fn generate_altrep_len(
    name: &syn::Ident,
    generics: &syn::Generics,
    len_field: &syn::Ident,
) -> TokenStream {
    let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();

    quote! {
        impl #impl_generics ::miniextendr_api::altrep_data::AltrepLen for #name #ty_generics #where_clause {
            fn altrep_len(&self) -> usize {
                self.#len_field
            }
        }
    }
}

/// Shared implementation for all non-list ALTREP derive macros.
///
/// Generates three items:
/// 1. `impl AltrepLen` -- delegates to the detected/specified length field
/// 2. `impl Alt*Data` -- the family-specific data trait with an `elt()` method
/// 3. Low-level trait impls via [`AltrepAttrs::generate_lowlevel`]
///
/// # Arguments
///
/// * `input` -- The `DeriveInput` from the proc-macro.
/// * `data_trait_path` -- The fully qualified path to the data trait
///   (e.g., `::miniextendr_api::altrep_data::AltIntegerData`).
/// * `gen_elt_impl` -- A closure that receives the optional `elt_field` and returns
///   a token stream for the `fn elt(...)` method body. If `elt_field` is `Some`, the
///   closure typically returns `self.{field}`; if `None`, it returns a family-appropriate
///   default (`NA_INTEGER`, `f64::NAN`, `0u8`, `Logical::Na`, `None`, or `Rcomplex { NAN, NAN }`).
/// * `family` -- The [`AltrepFamilyConfig`] for this type family.
///
/// # Errors
///
/// Returns `Err` if attribute parsing fails, no length field can be found, or
/// option validation fails.
fn derive_altrep_generic(
    input: syn::DeriveInput,
    data_trait_path: TokenStream,
    gen_elt_impl: impl FnOnce(Option<&syn::Ident>, Option<&syn::Ident>) -> TokenStream,
    family: &AltrepFamilyConfig,
) -> syn::Result<TokenStream> {
    let name = &input.ident;
    let generics = &input.generics;
    let attrs = AltrepAttrs::parse(&input)?;

    // In manual mode, skip AltrepLen + data trait generation — user provides their own.
    let data_traits = if attrs.manual {
        quote! {}
    } else {
        let len_field = attrs.get_len_field(&input)?;
        let altrep_len_impl = generate_altrep_len(name, generics, &len_field);
        let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();
        let elt_impl = gen_elt_impl(attrs.elt_field.as_ref(), attrs.elt_delegate.as_ref());
        quote! {
            #altrep_len_impl
            impl #impl_generics #data_trait_path for #name #ty_generics #where_clause {
                #elt_impl
            }
        }
    };

    let lowlevel_impl = attrs.generate_lowlevel(name, generics, family)?;

    // Generate full registration (TypedExternal, AltrepClass, RegisterAltrep, IntoR,
    // linkme entry, Ref/Mut).
    let class_name = attrs
        .class_name
        .as_deref()
        .unwrap_or(&name.to_string())
        .to_string();
    let registration_impl =
        crate::altrep::generate_direct_altrep_registration(&input, &class_name)?;

    Ok(quote! {
        #data_traits
        #lowlevel_impl
        #registration_impl
    })
}

/// Derive macro entry point for `AltrepInteger`.
///
/// Auto-implements `AltrepLen` and `AltIntegerData` for a struct with a length field.
/// The `elt()` method returns `self.{elt_field}` as `i32` if `#[altrep(elt = "...")]`
/// is specified, or `NA_INTEGER` by default.
///
/// Supports `#[altrep(dataptr)]` for direct `i32` data pointer access and
/// `#[altrep(subset)]` for `Extract_subset`.
pub fn derive_altrep_integer(input: syn::DeriveInput) -> syn::Result<TokenStream> {
    derive_altrep_generic(
        input,
        quote! { ::miniextendr_api::altrep_data::AltIntegerData },
        |elt_field, elt_delegate| {
            if let Some(d) = elt_delegate {
                quote! { fn elt(&self, i: usize) -> i32 { self.#d.elt(i) } }
            } else if let Some(f) = elt_field {
                quote! { fn elt(&self, _i: usize) -> i32 { self.#f } }
            } else {
                quote! { fn elt(&self, _i: usize) -> i32 { ::miniextendr_api::altrep_traits::NA_INTEGER } }
            }
        },
        &AltrepFamilyConfig {
            family_name: "AltrepInteger",
            dataptr_macro: Some(("__impl_altvec_dataptr", Some(quote! { i32 }))),
            string_dataptr: false,
            subset: true,
            methods_macro: "__impl_altinteger_methods",
            inferbase_macro: "impl_inferbase_integer",
            default_guard: "RUnwind",
            materializing_dataptr_macro: "__impl_altvec_integer_dataptr",
        },
    )
}

/// Derive macro entry point for `AltrepReal`.
///
/// Auto-implements `AltrepLen` and `AltRealData` for a struct with a length field.
/// The `elt()` method returns `self.{elt_field}` as `f64` if `#[altrep(elt = "...")]`
/// is specified, or `f64::NAN` (R's `NA_real_`) by default.
///
/// Supports `#[altrep(dataptr)]` for direct `f64` data pointer access and
/// `#[altrep(subset)]` for `Extract_subset`.
pub fn derive_altrep_real(input: syn::DeriveInput) -> syn::Result<TokenStream> {
    derive_altrep_generic(
        input,
        quote! { ::miniextendr_api::altrep_data::AltRealData },
        |elt_field, elt_delegate| {
            if let Some(d) = elt_delegate {
                quote! { fn elt(&self, i: usize) -> f64 { self.#d.elt(i) } }
            } else if let Some(f) = elt_field {
                quote! { fn elt(&self, _i: usize) -> f64 { self.#f } }
            } else {
                quote! { fn elt(&self, _i: usize) -> f64 { f64::NAN } }
            }
        },
        &AltrepFamilyConfig {
            family_name: "AltrepReal",
            dataptr_macro: Some(("__impl_altvec_dataptr", Some(quote! { f64 }))),
            string_dataptr: false,
            subset: true,
            methods_macro: "__impl_altreal_methods",
            inferbase_macro: "impl_inferbase_real",
            default_guard: "RUnwind",
            materializing_dataptr_macro: "__impl_altvec_real_dataptr",
        },
    )
}

/// Derive macro entry point for `AltrepLogical`.
///
/// Auto-implements `AltrepLen` and `AltLogicalData` for a struct with a length field.
/// The `elt()` method returns `self.{elt_field}.into()` as `Logical` if
/// `#[altrep(elt = "...")]` is specified, or `Logical::Na` by default.
///
/// Supports `#[altrep(dataptr)]` for direct `i32` data pointer access (logicals are
/// stored as `i32` in R) and `#[altrep(subset)]` for `Extract_subset`.
pub fn derive_altrep_logical(input: syn::DeriveInput) -> syn::Result<TokenStream> {
    derive_altrep_generic(
        input,
        quote! { ::miniextendr_api::altrep_data::AltLogicalData },
        |elt_field, elt_delegate| {
            if let Some(d) = elt_delegate {
                quote! { fn elt(&self, i: usize) -> ::miniextendr_api::altrep_data::Logical { self.#d.elt(i) } }
            } else if let Some(f) = elt_field {
                quote! { fn elt(&self, _i: usize) -> ::miniextendr_api::altrep_data::Logical { self.#f.into() } }
            } else {
                quote! { fn elt(&self, _i: usize) -> ::miniextendr_api::altrep_data::Logical { ::miniextendr_api::altrep_data::Logical::Na } }
            }
        },
        &AltrepFamilyConfig {
            family_name: "AltrepLogical",
            dataptr_macro: Some(("__impl_altvec_dataptr", Some(quote! { i32 }))),
            string_dataptr: false,
            subset: true,
            methods_macro: "__impl_altlogical_methods",
            inferbase_macro: "impl_inferbase_logical",
            default_guard: "RUnwind",
            materializing_dataptr_macro: "__impl_altvec_logical_dataptr",
        },
    )
}

/// Derive macro entry point for `AltrepRaw`.
///
/// Auto-implements `AltrepLen` and `AltRawData` for a struct with a length field.
/// The `elt()` method returns `self.{elt_field}` as `u8` if `#[altrep(elt = "...")]`
/// is specified, or `0u8` by default.
///
/// Supports `#[altrep(dataptr)]` for direct `u8` data pointer access and
/// `#[altrep(subset)]` for `Extract_subset`.
pub fn derive_altrep_raw(input: syn::DeriveInput) -> syn::Result<TokenStream> {
    derive_altrep_generic(
        input,
        quote! { ::miniextendr_api::altrep_data::AltRawData },
        |elt_field, elt_delegate| {
            if let Some(d) = elt_delegate {
                quote! { fn elt(&self, i: usize) -> u8 { self.#d.elt(i) } }
            } else if let Some(f) = elt_field {
                quote! { fn elt(&self, _i: usize) -> u8 { self.#f } }
            } else {
                quote! { fn elt(&self, _i: usize) -> u8 { 0 } }
            }
        },
        &AltrepFamilyConfig {
            family_name: "AltrepRaw",
            dataptr_macro: Some(("__impl_altvec_dataptr", Some(quote! { u8 }))),
            string_dataptr: false,
            subset: true,
            methods_macro: "__impl_altraw_methods",
            inferbase_macro: "impl_inferbase_raw",
            default_guard: "RUnwind",
            materializing_dataptr_macro: "__impl_altvec_raw_dataptr",
        },
    )
}

/// Derive macro entry point for `AltrepString`.
///
/// Auto-implements `AltrepLen` and `AltStringData` for a struct with a length field.
/// The `elt()` method returns `Some(self.{elt_field}.as_ref())` as `Option<&str>` if
/// `#[altrep(elt = "...")]` is specified, or `None` (R's `NA_character_`) by default.
///
/// String ALTREP supports `#[altrep(dataptr)]` for materialized `STRSXP` dataptr
/// (via `__impl_altvec_string_dataptr`) and `#[altrep(subset)]` for `Extract_subset`.
/// Note: String dataptr materializes the entire vector into a cached `STRSXP` in the
/// data2 slot.
pub fn derive_altrep_string(input: syn::DeriveInput) -> syn::Result<TokenStream> {
    derive_altrep_generic(
        input,
        quote! { ::miniextendr_api::altrep_data::AltStringData },
        |elt_field, elt_delegate| {
            if let Some(d) = elt_delegate {
                quote! { fn elt(&self, i: usize) -> ::core::option::Option<&str> { self.#d.elt(i) } }
            } else if let Some(f) = elt_field {
                quote! { fn elt(&self, _i: usize) -> ::core::option::Option<&str> { ::core::option::Option::Some(self.#f.as_ref()) } }
            } else {
                quote! { fn elt(&self, _i: usize) -> ::core::option::Option<&str> { ::core::option::Option::None } }
            }
        },
        &AltrepFamilyConfig {
            family_name: "AltrepString",
            dataptr_macro: None,
            string_dataptr: true,
            subset: true,
            methods_macro: "__impl_altstring_methods",
            inferbase_macro: "impl_inferbase_string",
            // String elt calls Rf_mkCharLenCE; dataptr calls Rf_allocVector + SET_STRING_ELT.
            // These R API calls can longjmp — must use RUnwind.
            default_guard: "RUnwind",
            // String has no typed contiguous dataptr; its default/dataptr arms
            // both route through `__impl_altvec_string_dataptr!`.
            materializing_dataptr_macro: "__impl_altvec_string_dataptr",
        },
    )
}

/// Derive macro entry point for `AltrepComplex`.
///
/// Auto-implements `AltrepLen` and `AltComplexData` for a struct with a length field.
/// The `elt()` method returns `self.{elt_field}` as `Rcomplex` if
/// `#[altrep(elt = "...")]` is specified, or `Rcomplex { r: NAN, i: NAN }` by default.
///
/// Supports `#[altrep(dataptr)]` for direct `Rcomplex` data pointer access and
/// `#[altrep(subset)]` for `Extract_subset`.
pub fn derive_altrep_complex(input: syn::DeriveInput) -> syn::Result<TokenStream> {
    derive_altrep_generic(
        input,
        quote! { ::miniextendr_api::altrep_data::AltComplexData },
        |elt_field, elt_delegate| {
            if let Some(d) = elt_delegate {
                quote! { fn elt(&self, i: usize) -> ::miniextendr_api::Rcomplex { self.#d.elt(i) } }
            } else if let Some(f) = elt_field {
                quote! { fn elt(&self, _i: usize) -> ::miniextendr_api::Rcomplex { self.#f } }
            } else {
                quote! {
                    fn elt(&self, _i: usize) -> ::miniextendr_api::Rcomplex {
                        ::miniextendr_api::Rcomplex { r: f64::NAN, i: f64::NAN }
                    }
                }
            }
        },
        &AltrepFamilyConfig {
            family_name: "AltrepComplex",
            dataptr_macro: Some((
                "__impl_altvec_dataptr",
                Some(quote! { ::miniextendr_api::Rcomplex }),
            )),
            string_dataptr: false,
            subset: true,
            methods_macro: "__impl_altcomplex_methods",
            inferbase_macro: "impl_inferbase_complex",
            default_guard: "RUnwind",
            materializing_dataptr_macro: "__impl_altvec_complex_dataptr",
        },
    )
}

/// Derive macro entry point for `AltrepList`.
///
/// Auto-implements `AltrepLen` and `AltListData` for a struct with a length field.
/// The `elt()` method returns `self.{elt_field}[i]` as `SEXP` if
/// `#[altrep(elt = "...")]` is specified (the field should be indexable and return `SEXP`),
/// or `R_NilValue` by default.
///
/// List ALTREP does **not** support `#[altrep(dataptr)]` or `#[altrep(subset)]` -- both
/// are rejected at compile time. `#[altrep(serialize)]` is supported. The class
/// takes R's writes through `altrep_impl::altlist_set_elt`, which copies the
/// elements into data2 on the first one; `Elt` reads data2 from then on.
pub fn derive_altrep_list(input: syn::DeriveInput) -> syn::Result<TokenStream> {
    let name = &input.ident;
    let generics = &input.generics;
    let attrs = AltrepAttrs::parse(&input)?;
    let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();

    // In manual mode, skip AltrepLen + AltListData generation.
    let data_traits = if attrs.manual {
        quote! {}
    } else {
        let len_field = attrs.get_len_field(&input)?;
        let altrep_len_impl = generate_altrep_len(name, generics, &len_field);
        let (impl_generics, ty_generics, where_clause) = generics.split_for_impl();

        let elt_impl = if let Some(ref elt_field) = attrs.elt_field {
            quote! {
                fn elt(&self, i: usize) -> ::miniextendr_api::SEXP {
                    self.#elt_field[i]
                }
            }
        } else {
            quote! {
                fn elt(&self, _i: usize) -> ::miniextendr_api::SEXP {
                    ::miniextendr_api::SEXP::nil()
                }
            }
        };

        quote! {
            #altrep_len_impl
            impl #impl_generics ::miniextendr_api::altrep_data::AltListData for #name #ty_generics #where_clause {
                #elt_impl
            }
        }
    };

    // List does not support dataptr or subset
    for opt in &attrs.lowlevel_options {
        if opt == "dataptr" || opt == "subset" {
            return Err(syn::Error::new(
                opt.span(),
                format!("`{opt}` is not supported for AltrepList"),
            ));
        }
    }

    let has_serialize = attrs.lowlevel_options.iter().any(|o| o == "serialize");

    let lowlevel_impl = if !attrs.generate_lowlevel {
        quote! {}
    } else {
        // Direct emit (#933). The non-serialize arm inlines the body of the
        // retired `impl_altlist_from_data!` delegation: `__impl_altrep_base!`
        // with an explicit guard is token-identical to that macro's
        // hand-written `Altrep` impl, and the `elt` body matches its
        // `altrep_extract_ref` path. The serialize arm keeps its historical
        // `altrep_data1_as` elt body — switching it to `AltrepExtract` would
        // change behaviour for types that override extraction.
        let guard = attrs
            .guard
            .as_ref()
            .cloned()
            .unwrap_or_else(|| syn::Ident::new("RUnwind", proc_macro2::Span::call_site()));
        let duplicate = attrs.duplicate_methods();
        let base_impl = if has_serialize {
            quote! { ::miniextendr_api::__impl_altrep_base!(#name #ty_generics, #guard, with_serialize #duplicate); }
        } else {
            quote! { ::miniextendr_api::__impl_altrep_base!(#name #ty_generics, #guard #duplicate); }
        };
        // Once `Set_elt` has copied the values into data2, they are R's.
        let written_elt = quote! {
            if let ::core::option::Option::Some(data2) = unsafe { ::miniextendr_api::altrep_data::materialized_altrep_data2(x) } {
                return ::miniextendr_api::SexpExt::vector_elt(&data2, i);
            }
        };
        let elt_impl = if has_serialize {
            quote! {
                fn elt(x: ::miniextendr_api::SEXP, i: ::miniextendr_api::R_xlen_t) -> ::miniextendr_api::SEXP {
                    #written_elt
                    // No `RefCell` borrow for the ALTREP data1 read, until #2103.
                    unsafe { ::miniextendr_api::altrep_data1_as::<#name #ty_generics>(x) }
                        .map(|d| <#name #ty_generics as ::miniextendr_api::altrep_data::AltListData>::elt(unsafe { d.as_ref_unchecked() }, i.max(0) as usize))
                        .unwrap_or(::miniextendr_api::SEXP::nil())
                }
            }
        } else {
            quote! {
                fn elt(x: ::miniextendr_api::SEXP, i: ::miniextendr_api::R_xlen_t) -> ::miniextendr_api::SEXP {
                    #written_elt
                    let data = unsafe {
                        <#name #ty_generics as ::miniextendr_api::altrep_data::AltrepExtract>::altrep_extract_ref(x)
                    };
                    <#name #ty_generics as ::miniextendr_api::altrep_data::AltListData>::elt(data, i.max(0) as usize)
                }
            }
        };
        quote! {
            #base_impl
            impl #impl_generics ::miniextendr_api::altrep_traits::AltVec for #name #ty_generics #where_clause {}
            impl #impl_generics ::miniextendr_api::altrep_traits::AltList for #name #ty_generics #where_clause {
                #elt_impl

                const HAS_SET_ELT: bool = true;

                fn set_elt(x: ::miniextendr_api::SEXP, i: ::miniextendr_api::R_xlen_t, v: ::miniextendr_api::SEXP) {
                    unsafe { ::miniextendr_api::altrep_impl::altlist_set_elt::<#name #ty_generics>(x, i, v) }
                }
            }
            ::miniextendr_api::impl_inferbase_list!(#name #ty_generics);
        }
    };

    // Generate full registration (TypedExternal, AltrepClass, RegisterAltrep, IntoR,
    // linkme entry, Ref/Mut) — same as derive_altrep_generic.
    let class_name = attrs
        .class_name
        .as_deref()
        .unwrap_or(&name.to_string())
        .to_string();
    let registration_impl =
        crate::altrep::generate_direct_altrep_registration(&input, &class_name)?;

    Ok(quote! {
        #data_traits
        #lowlevel_impl
        #registration_impl
    })
}

// region: Public helper for derive(Altrep) with base parameter