miniextendr_macros/

struct_enum_dispatch.rs

//! Dispatch `#[miniextendr]` on structs and enums to the appropriate derive helpers.
//!
//! This module handles `#[miniextendr]` when applied to structs or enums (not functions,
//! impl blocks, or traits). It dispatches to the correct derive helper based on:
//!
//! - Item shape (structs → ExternalPtr, fieldless enums → RFactor by default)
//! - Explicit mode attributes (`list`, `dataframe`, `externalptr`, `match_arg`, `factor`)
//! - Preference markers (`prefer = "..."`)
//!
//! # Disambiguation table
//!
//! | Syntax | Result |
//! |---|---|
//! | `#[miniextendr]` / `#[miniextendr(externalptr)]` on struct | ExternalPtr |
//! | `#[miniextendr(list)]` on struct | IntoList + TryFromList + PreferList |
//! | `#[miniextendr(dataframe)]` on struct | DataFrameRow (companion has IntoR) |
//! | `#[miniextendr(prefer = "list" / "dataframe" / "externalptr")]` on struct | Same as the explicit mode |
//! | `#[miniextendr(prefer = "native")]` on struct | ExternalPtr without its IntoR + PreferRNativeType |
//! | `#[miniextendr(class = "...", base = "...")]` on struct | Error: use an ALTREP derive |
//! | `#[miniextendr]` on fieldless enum | RFactor |
//! | `#[miniextendr(match_arg)]` on fieldless enum | MatchArg |

/// Parsed attributes for `#[miniextendr]` on structs/enums.
///
/// These attributes control which derive path is taken when `#[miniextendr]`
/// is applied to a struct or enum.
struct StructEnumAttrs {
    /// Removed ALTREP class option; parsed only to reject it with migration guidance.
    class: Option<String>,
    /// Removed ALTREP base option; parsed only to reject it with migration guidance.
    base: Option<String>,
    /// Derive `IntoList` + `TryFromList` + `PreferList` for struct-to-list round-tripping.
    list: bool,
    /// Derive `DataFrameRow` for struct-to-data-frame conversion.
    dataframe: bool,
    /// Explicitly select the `ExternalPtr` derive.
    externalptr: bool,
    /// Derive `MatchArg` for enum (single-selection from R character scalar).
    match_arg: bool,
    /// Derive `RFactor` for enum (R factor representation).
    factor: bool,
    /// Preference marker string: `"externalptr"`, `"list"`, `"dataframe"`, or `"native"`.
    /// Acts as a soft mode selector when no explicit mode attribute is set.
    prefer: Option<String>,
}

/// Parses the attribute arguments of `#[miniextendr(...)]` when applied to a struct or enum.
///
/// Supports path-style flags (`list`, `dataframe`, `externalptr`, `match_arg`, `factor`)
/// and key-value pairs (`class = "..."`, `base = "..."`, `prefer = "..."`).
///
/// Returns a [`StructEnumAttrs`] on success, or a compile error if an unknown attribute is found.
fn parse_attrs(attr: proc_macro::TokenStream) -> syn::Result<StructEnumAttrs> {
    use syn::parse::Parser;

    let mut attrs = StructEnumAttrs {
        class: None,
        base: None,
        list: false,
        dataframe: false,
        externalptr: false,
        match_arg: false,
        factor: false,
        prefer: None,
    };

    // Parse as comma-separated meta items
    let parser = syn::punctuated::Punctuated::<syn::Meta, syn::Token![,]>::parse_terminated;
    let metas = parser.parse(attr)?;

    for meta in &metas {
        match meta {
            syn::Meta::Path(path) => {
                let ident = path
                    .get_ident()
                    .ok_or_else(|| syn::Error::new_spanned(path, "expected identifier"))?;
                match ident.to_string().as_str() {
                    "list" => attrs.list = true,
                    "dataframe" => attrs.dataframe = true,
                    "externalptr" => attrs.externalptr = true,
                    "match_arg" => attrs.match_arg = true,
                    "factor" => attrs.factor = true,
                    _ => {
                        return Err(syn::Error::new_spanned(
                            ident,
                            format!(
                                "unknown #[miniextendr] attribute `{}`; expected one of: \
                                 list, dataframe, externalptr, match_arg, factor, prefer, class, base",
                                ident
                            ),
                        ));
                    }
                }
            }
            syn::Meta::NameValue(nv) => {
                let key = nv
                    .path
                    .get_ident()
                    .map(|i| i.to_string())
                    .unwrap_or_default();
                if let syn::Expr::Lit(syn::ExprLit {
                    lit: syn::Lit::Str(s),
                    ..
                }) = &nv.value
                {
                    match key.as_str() {
                        "class" => attrs.class = Some(s.value()),
                        "base" => attrs.base = Some(s.value()),
                        "prefer" => attrs.prefer = Some(s.value()),
                        _ => {
                            return Err(syn::Error::new_spanned(
                                &nv.path,
                                format!(
                                    "unknown #[miniextendr] attribute `{}`; expected one of: \
                                     class, base, prefer",
                                    key
                                ),
                            ));
                        }
                    }
                }
            }
            syn::Meta::List(list) => {
                return Err(syn::Error::new_spanned(
                    list,
                    "unexpected list-style attribute; use path (`list`) or key-value (`class = \"...\"`) syntax",
                ));
            }
        }
    }

    Ok(attrs)
}

/// Returns `true` if every variant of the enum is a unit variant (no fields).
fn is_fieldless_enum(item: &syn::ItemEnum) -> bool {
    item.variants
        .iter()
        .all(|v| matches!(v.fields, syn::Fields::Unit))
}

/// Main dispatch entry point for `#[miniextendr]` on a struct or enum.
///
/// Attempts to parse the item as a struct first, then as an enum.
/// Dispatches to the appropriate derive path based on the parsed attributes
/// and item shape (field count, variant structure).
///
/// Returns the original item plus any generated trait implementations as a combined token stream.
pub fn expand_struct_or_enum(
    attr: proc_macro::TokenStream,
    item: proc_macro::TokenStream,
) -> proc_macro::TokenStream {
    // Try parsing as struct first, then enum
    if let Ok(item_struct) = syn::parse::<syn::ItemStruct>(item.clone()) {
        return expand_struct(attr, item, &item_struct);
    }

    if let Ok(item_enum) = syn::parse::<syn::ItemEnum>(item.clone()) {
        return expand_enum(attr, item, &item_enum);
    }

    // A function (or a method in an impl or trait) whose Rust `...` is not the
    // last parameter doesn't parse as one, so it lands here: name the cause (#1737).
    if let Some(found) = crate::misplaced_dots::find(item.into()) {
        return syn::Error::new_spanned(
            found.dots,
            crate::misplaced_dots::message(found.name.as_deref()),
        )
        .into_compile_error()
        .into();
    }

    // If neither, give a helpful error
    syn::Error::new(
        proc_macro2::Span::call_site(),
        "#[miniextendr] on non-function items requires a struct or enum",
    )
    .into_compile_error()
    .into()
}

/// Dispatches `#[miniextendr]` on a struct to the correct derive path.
///
/// Decision logic:
/// - ALTREP attrs (`class`/`base`): compile error with migration guidance
///   (ALTREP via `#[miniextendr]` is removed — use the `#[derive(Altrep*)]`
///   family)
/// - `list` mode: `#[derive(IntoList, TryFromList, PreferList)]`
/// - `dataframe` mode: `#[derive(DataFrameRow)]` (the companion gets `IntoR`)
/// - Default or explicit `externalptr`: `ExternalPtr`
/// - `prefer = "native"`: `ExternalPtr` (without the `IntoExternalPtr` marker,
///   #1283) + `PreferRNativeType` marker
fn expand_struct(
    attr: proc_macro::TokenStream,
    item: proc_macro::TokenStream,
    item_struct: &syn::ItemStruct,
) -> proc_macro::TokenStream {
    let attrs = match parse_attrs(attr.clone()) {
        Ok(a) => a,
        Err(e) => return e.into_compile_error().into(),
    };

    let has_altrep_attrs = attrs.class.is_some() || attrs.base.is_some();
    let has_mode_attr = attrs.list || attrs.dataframe || attrs.externalptr;

    // Resolve prefer into a mode if no explicit mode attr is set
    let effective_list = attrs.list || (!has_mode_attr && attrs.prefer.as_deref() == Some("list"));
    let effective_dataframe =
        attrs.dataframe || (!has_mode_attr && attrs.prefer.as_deref() == Some("dataframe"));
    let effective_externalptr =
        attrs.externalptr || (!has_mode_attr && attrs.prefer.as_deref() == Some("externalptr"));
    let effective_mode = effective_list || effective_dataframe || effective_externalptr;

    // ALTREP attrs without a mode: error with migration guidance.
    // ALTREP via #[miniextendr] is removed — use #[derive(Altrep)] instead.
    if has_altrep_attrs && !effective_mode {
        return syn::Error::new(
            item_struct.ident.span(),
            "#[miniextendr] no longer supports ALTREP (class/base attributes). \
             Use #[derive(miniextendr_api::Altrep)] with #[altrep(class = \"...\")] instead.",
        )
        .into_compile_error()
        .into();
    }

    // Reject ALTREP attrs on non-ALTREP paths
    if has_altrep_attrs && effective_mode {
        return syn::Error::new(
            item_struct.ident.span(),
            "cannot combine ALTREP attributes (class, base) with mode attributes (list, dataframe, externalptr)",
        )
        .into_compile_error()
        .into();
    }

    // Check for conflicting mode attrs
    let mode_count = [effective_list, effective_dataframe, effective_externalptr]
        .iter()
        .filter(|&&b| b)
        .count();
    if mode_count > 1 {
        return syn::Error::new(
            item_struct.ident.span(),
            "only one of `list`, `dataframe`, `externalptr` can be specified",
        )
        .into_compile_error()
        .into();
    }

    // Validate prefer value
    if let Some(ref prefer) = attrs.prefer
        && !matches!(
            prefer.as_str(),
            "externalptr" | "list" | "dataframe" | "native"
        )
    {
        return syn::Error::new(
            item_struct.ident.span(),
            format!(
                "unknown prefer value `{}`; expected one of: externalptr, list, dataframe, native",
                prefer
            ),
        )
        .into_compile_error()
        .into();
    }

    // Emit actual derives so rustc registers their helper attributes (#2024).
    // Calling their implementations directly would leave unclaimed helpers on
    // the struct; stripping them would hide options from other derives.
    if effective_list {
        return quote::quote! {
            #[derive(
                ::miniextendr_api::IntoList,
                ::miniextendr_api::TryFromList,
                ::miniextendr_api::PreferList,
            )]
            #item_struct
        }
        .into();
    }

    if effective_dataframe {
        // Row columns do not need an IntoList implementation on the row.
        return quote::quote! {
            #[derive(::miniextendr_api::DataFrameRow)]
            #item_struct
        }
        .into();
    }

    // The ExternalPtr helper needs the native preference flag below.
    let derive_input: syn::DeriveInput = match syn::parse(item.clone()) {
        Ok(d) => d,
        Err(e) => return e.into_compile_error().into(),
    };
    let derive_input = strip_miniextendr_attrs(derive_input);
    let item_ts: proc_macro2::TokenStream = item.into();

    // Default for multi-field or explicit externalptr: ExternalPtr
    // Also handles prefer = "native" (ExternalPtr + native preference marker)
    let result = (|| -> syn::Result<proc_macro2::TokenStream> {
        // Suppress the `IntoExternalPtr` marker (and its blanket `IntoR`) for
        // `prefer = "native"` so the concrete `AsRNative` `IntoR` from
        // `derive_prefer_rnative` below is the type's sole `IntoR` (E0119, #1283).
        let external_ptr = crate::externalptr_derive::derive_external_ptr(
            derive_input.clone(),
            attrs.prefer.as_deref() != Some("native"),
        )?;

        // Apply native preference marker if specified
        let prefer = if attrs.prefer.as_deref() == Some("native") {
            crate::list_derive::derive_prefer_rnative(derive_input)?
        } else {
            proc_macro2::TokenStream::new()
        };

        Ok(quote::quote! {
            #item_ts
            #external_ptr
            #prefer
        })
    })();
    result.unwrap_or_else(|e| e.into_compile_error()).into()
}

/// Dispatches `#[miniextendr]` on a fieldless enum to the correct derive path.
///
/// Only C-style (fieldless) enums are supported. Dispatches to:
/// - `match_arg` mode: `MatchArg` derive (single-selection from R character scalar)
/// - `factor` mode or default: `RFactor` derive (R factor representation)
fn expand_enum(
    attr: proc_macro::TokenStream,
    item: proc_macro::TokenStream,
    item_enum: &syn::ItemEnum,
) -> proc_macro::TokenStream {
    let attrs = match parse_attrs(attr) {
        Ok(a) => a,
        Err(e) => return e.into_compile_error().into(),
    };

    if !is_fieldless_enum(item_enum) {
        return syn::Error::new(
            item_enum.ident.span(),
            "#[miniextendr] on enums requires all variants to be fieldless (C-style)",
        )
        .into_compile_error()
        .into();
    }

    let derive_input: syn::DeriveInput = match syn::parse(item.clone()) {
        Ok(d) => d,
        Err(e) => return e.into_compile_error().into(),
    };
    let derive_input = strip_miniextendr_attrs(derive_input);

    let item_ts: proc_macro2::TokenStream = item.into();

    if attrs.match_arg {
        // MatchArg mode
        let result = crate::match_arg_derive::derive_match_arg(derive_input);
        return match result {
            Ok(ts) => quote::quote! { #item_ts #ts }.into(),
            Err(e) => e.into_compile_error().into(),
        };
    }

    if attrs.factor {
        // Explicit factor mode
        let result = crate::factor_derive::derive_r_factor(derive_input);
        return match result {
            Ok(ts) => quote::quote! { #item_ts #ts }.into(),
            Err(e) => e.into_compile_error().into(),
        };
    }

    // Default: RFactor
    let result = crate::factor_derive::derive_r_factor(derive_input);
    match result {
        Ok(ts) => quote::quote! { #item_ts #ts }.into(),
        Err(e) => e.into_compile_error().into(),
    }
}

/// Strip `#[miniextendr(...)]` attributes from a DeriveInput.
///
/// Derive helpers don't expect `#[miniextendr]` attributes and may fail or
/// misinterpret them. We strip them before forwarding.
fn strip_miniextendr_attrs(mut input: syn::DeriveInput) -> syn::DeriveInput {
    input
        .attrs
        .retain(|attr| !attr.path().is_ident("miniextendr"));
    input
}