miniextendr_macros/

return_wrap.rs

//! One explicit class-wrapping decision for marker and attribute spellings.

use crate::miniextendr_impl::ClassSystem;
use crate::type_inspect::first_type_argument;
use proc_macro2::TokenStream;
use quote::quote;
use syn::{GenericArgument, PathArguments, ReturnType, Type};

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Container {
    Option,
    Result,
    Vec,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) enum ConversionKind {
    To,
    From,
}

#[derive(Debug, Clone)]
pub struct ReturnWrap {
    system: ClassSystem,
    target: String,
    containers: Vec<Container>,
    typed: bool,
    pub(crate) conversion: Option<ConversionKind>,
}

pub(crate) fn parse_system(value: &syn::LitStr) -> syn::Result<ClassSystem> {
    value
        .value()
        .parse()
        .map_err(|message| syn::Error::new(value.span(), message))
}

fn marker_system(name: &syn::Ident) -> Option<ClassSystem> {
    Some(match name.to_string().as_str() {
        "WrapAsR6" => ClassSystem::R6,
        "WrapAsS7" | "ConvertTo" | "ConvertFrom" => ClassSystem::S7,
        "WrapAsS4" => ClassSystem::S4,
        "WrapAsS3" => ClassSystem::S3,
        "WrapAsEnv" => ClassSystem::Env,
        "WrapAsVctrs" => ClassSystem::Vctrs,
        _ => return None,
    })
}

pub(crate) fn contains_marker(ty: &Type) -> bool {
    match ty {
        Type::Path(path) => path.path.segments.iter().any(|segment| {
            marker_system(&segment.ident).is_some()
                || match &segment.arguments {
                    PathArguments::AngleBracketed(args) => args
                        .args
                        .iter()
                        .any(|arg| matches!(arg, GenericArgument::Type(ty) if contains_marker(ty))),
                    _ => false,
                }
        }),
        Type::Reference(ty) => contains_marker(&ty.elem),
        Type::Paren(ty) => contains_marker(&ty.elem),
        Type::Group(ty) => contains_marker(&ty.elem),
        Type::Slice(ty) => contains_marker(&ty.elem),
        Type::Array(ty) => contains_marker(&ty.elem),
        Type::Tuple(ty) => ty.elems.iter().any(contains_marker),
        _ => false,
    }
}

/// Peel a marker under the supported boundary containers, or select the same
/// plan from `wrap = "..."`. Visibility has already been peeled by the caller.
pub(crate) fn resolve(
    output: &ReturnType,
    attribute: Option<ClassSystem>,
) -> syn::Result<(Option<ReturnWrap>, ReturnType)> {
    let ReturnType::Type(arrow, ty) = output else {
        if attribute.is_some() {
            return Err(syn::Error::new_spanned(
                output,
                "`wrap` requires a named class return value",
            ));
        }
        return Ok((None, output.clone()));
    };
    if attribute.is_none() && !contains_marker(ty) {
        return Ok((None, output.clone()));
    }
    let mut leaf = ty.as_ref();
    let mut containers = Vec::new();
    while let Type::Path(path) = leaf {
        let segment = path.path.segments.last().expect("type path has a segment");
        let container = match segment.ident.to_string().as_str() {
            "Option" => Container::Option,
            "Result" => Container::Result,
            "Vec" => Container::Vec,
            _ => break,
        };
        let PathArguments::AngleBracketed(args) = &segment.arguments else {
            break;
        };
        if container == Container::Result
            && let Some(GenericArgument::Type(error)) = args.args.iter().nth(1)
        {
            if contains_marker(error) {
                return Err(syn::Error::new_spanned(
                    error,
                    "WrapAs* belongs on the successful Result payload",
                ));
            }
            if matches!(error, Type::Tuple(tuple) if tuple.elems.is_empty()) {
                return Err(syn::Error::new_spanned(
                    error,
                    "explicit class wrapping does not support Result<T, ()>; use a non-unit error type",
                ));
            }
        }
        let Some(GenericArgument::Type(inner)) = args.args.first() else {
            break;
        };
        containers.push(container);
        leaf = inner;
    }
    if !matches!(
        containers.as_slice(),
        [] | [Container::Option]
            | [Container::Result]
            | [Container::Vec]
            | [Container::Option, Container::Vec]
            | [Container::Result, Container::Vec]
    ) {
        return Err(syn::Error::new_spanned(
            ty,
            "explicit class wrapping supports T, Option<T>, Result<T, E>, Vec<T>, Option<Vec<T>>, or Result<Vec<T>, E>",
        ));
    }
    let marker = if let Type::Path(path) = leaf {
        path.path
            .segments
            .last()
            .and_then(|segment| marker_system(&segment.ident).map(|system| (system, segment)))
    } else {
        None
    };
    let conversion =
        marker
            .as_ref()
            .and_then(|(_, segment)| match segment.ident.to_string().as_str() {
                "ConvertTo" => Some(ConversionKind::To),
                "ConvertFrom" => Some(ConversionKind::From),
                _ => None,
            });
    let typed = marker.is_some();
    let (system, payload) = match marker {
        Some((system, segment)) => {
            if attribute.is_some_and(|attribute| attribute != system) {
                return Err(syn::Error::new_spanned(
                    ty,
                    "the WrapAs* marker and `wrap` attribute select different class systems",
                ));
            }
            let inner = first_type_argument(segment)
                .ok_or_else(|| {
                    syn::Error::new_spanned(segment, "WrapAs* requires one class type argument")
                })?
                .clone();
            if !matches!(&segment.arguments, PathArguments::AngleBracketed(args) if args.args.len() == 1)
            {
                return Err(syn::Error::new_spanned(
                    segment,
                    "WrapAs* requires exactly one class type argument",
                ));
            }
            (system, inner)
        }
        None => (attribute.ok_or_else(|| syn::Error::new_spanned(ty, "place WrapAs* directly around the class payload, inside Option, Result, or Vec"))?, leaf.clone()),
    };
    // An `ExternalPtr<Class>` payload names `Class`; the Rust return type keeps
    // the handle, which converts to the same `EXTPTRSXP` (#1375).
    let leaf = crate::type_inspect::peel_external_ptr(&payload);
    let Type::Path(path) = leaf else {
        return Err(syn::Error::new_spanned(
            leaf,
            "explicit wrapping requires an owned, named class type",
        ));
    };
    let segment = path.path.segments.last().expect("type path has a segment");
    if !matches!(segment.arguments, PathArguments::None) || contains_marker(leaf) {
        return Err(syn::Error::new_spanned(
            leaf,
            "WrapAs* must be closest to the named class type; put containers and visibility outside it",
        ));
    }
    let target = crate::naming::ident_name(&segment.ident);
    // Validate through shared borrows above, then replace the known payload slot.
    let mut peeled = (**ty).clone();
    let mut slot = &mut peeled;
    for _ in &containers {
        let Type::Path(path) = slot else {
            unreachable!("validated container path")
        };
        let PathArguments::AngleBracketed(args) = &mut path
            .path
            .segments
            .last_mut()
            .expect("validated path")
            .arguments
        else {
            unreachable!("validated container arguments")
        };
        let GenericArgument::Type(inner) = args.args.first_mut().expect("validated payload") else {
            unreachable!("validated type argument")
        };
        slot = inner;
    }
    *slot = payload;

    Ok((
        Some(ReturnWrap {
            system,
            target,
            containers,
            typed,
            conversion,
        }),
        ReturnType::Type(*arrow, Box::new(peeled)),
    ))
}

impl ReturnWrap {
    pub(crate) fn system(&self) -> ClassSystem {
        self.system
    }
    pub(crate) fn target(&self) -> &str {
        &self.target
    }
    pub(crate) fn set_target(&mut self, target: String) {
        self.target = target;
    }
    pub(crate) fn has_vector(&self) -> bool {
        self.containers.contains(&Container::Vec)
    }

    /// `Option<Class>`, the one wrapped shape without an `IntoR` impl for its
    /// `Option` (the orphan rule refuses one in the class's crate): the C wrapper
    /// converts the payload and gives `NULL` for `None`
    /// (`ReturnHandling::OptionClassPayload`).
    pub(crate) fn is_optional_class(&self) -> bool {
        self.containers == [Container::Option]
    }

    /// Unwrap only syntactic marker values; attributes keep the user's value.
    pub(crate) fn prepare_value(&self, call: TokenStream) -> TokenStream {
        fn map(call: TokenStream, containers: &[Container]) -> TokenStream {
            match containers.split_first() {
                None => quote!((#call).0),
                Some((container, rest)) => {
                    let inner = map(quote!(__mx_value), rest);
                    if *container == Container::Vec {
                        quote!((#call).into_iter().map(|__mx_value| #inner).collect::<::std::vec::Vec<_>>())
                    } else {
                        quote!((#call).map(|__mx_value| #inner))
                    }
                }
            }
        }
        if self.typed {
            map(call, &self.containers)
        } else {
            call
        }
    }

    /// Emit the chosen constructor directly; no write-time registry lookup.
    pub(crate) fn r_expression(&self, value: &str, self_type: Option<&str>) -> String {
        let target = if self.target == "Self" {
            self_type.unwrap_or("Self")
        } else {
            &self.target
        };
        let wrap = |value: &str| match self.system {
            ClassSystem::R6 => format!("{target}$new(.ptr = {value})"),
            ClassSystem::S7 => format!("{target}(.ptr = {value})"),
            ClassSystem::S4 => format!("methods::new(\"{target}\", ptr = {value})"),
            ClassSystem::S3 | ClassSystem::Env => {
                format!("structure({value}, class = \"{target}\")")
            }
            ClassSystem::Vctrs => {
                format!("structure({value}, class = unique(c(\"{target}\", class({value}))))")
            }
        };
        let wrapped = if self.containers.contains(&Container::Vec) {
            format!("lapply({value}, function(.item) {})", wrap(".item"))
        } else {
            wrap(value)
        };
        // `None` arrives as `NULL` (an `Option` converts as a function's does);
        // no constructor takes it, and `lapply()` would turn it into `list()`.
        if self.containers.first() == Some(&Container::Option) {
            format!("if (is.null({value})) NULL else {wrapped}")
        } else {
            wrapped
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use quote::ToTokens;

    #[test]
    fn marker_and_attribute_share_each_system_and_container_plan() {
        for (marker, system) in [
            ("WrapAsR6", ClassSystem::R6),
            ("WrapAsS7", ClassSystem::S7),
            ("WrapAsS4", ClassSystem::S4),
            ("WrapAsS3", ClassSystem::S3),
            ("WrapAsEnv", ClassSystem::Env),
            ("WrapAsVctrs", ClassSystem::Vctrs),
        ] {
            for shape in [
                "{}",
                "Option<{}>",
                "Result<{}, String>",
                "Vec<{}>",
                "Option<Vec<{}>>",
                "Result<Vec<{}>, String>",
            ] {
                let typed: ReturnType = syn::parse_str(&format!(
                    "-> {}",
                    shape.replace("{}", &format!("miniextendr_api::{marker}<Board>"))
                ))
                .unwrap();
                let plain: ReturnType =
                    syn::parse_str(&format!("-> {}", shape.replace("{}", "Board"))).unwrap();
                let (a, output) = resolve(&typed, None).unwrap();
                let (b, _) = resolve(&plain, Some(system)).unwrap();
                assert_eq!(
                    output.to_token_stream().to_string(),
                    plain.to_token_stream().to_string()
                );
                assert_eq!(
                    a.unwrap().r_expression(".val", None),
                    b.unwrap().r_expression(".val", None)
                );
            }
        }
    }
    /// An `Option` return is `NULL` for `None` (#2088): the wrap lets it through.
    #[test]
    fn optional_wraps_let_null_through() {
        for (shape, guarded) in [
            ("{}", false),
            ("Option<{}>", true),
            ("Result<{}, String>", false),
            ("Vec<{}>", false),
            ("Option<Vec<{}>>", true),
            ("Result<Vec<{}>, String>", false),
        ] {
            let output: ReturnType =
                syn::parse_str(&format!("-> {}", shape.replace("{}", "WrapAsR6<Board>"))).unwrap();
            let (plan, _) = resolve(&output, None).unwrap();
            let plan = plan.unwrap();
            assert_eq!(plan.is_optional_class(), shape == "Option<{}>", "{shape}");
            let expr = plan.r_expression(".val", None);
            assert_eq!(
                expr.starts_with("if (is.null(.val)) NULL else "),
                guarded,
                "{shape}: {expr}"
            );
        }
    }

    #[test]
    fn rejects_misplaced_markers_and_conflicting_systems() {
        for (output, message) in [
            ("-> WrapAsR6<Vec<Board>>", "closest to the named class"),
            (
                "-> Result<Board, WrapAsR6<Problem>>",
                "successful Result payload",
            ),
            (
                "-> Option<Option<WrapAsR6<Board>>>",
                "supports T, Option<T>",
            ),
            ("-> Result<WrapAsR6<Board>, ()>", "non-unit error type"),
            (
                "-> (WrapAsR6<Board>, i32)",
                "directly around the class payload",
            ),
            ("-> WrapAsR6<&Board>", "owned, named class type"),
            ("-> WrapAsR6<WrapAsS7<Board>>", "closest to the named class"),
        ] {
            let output = syn::parse_str(output).unwrap();
            assert!(
                resolve(&output, None)
                    .unwrap_err()
                    .to_string()
                    .contains(message)
            );
        }
        let output = syn::parse_quote!(-> WrapAsR6<Board>);
        assert!(
            resolve(&output, Some(ClassSystem::S7))
                .unwrap_err()
                .to_string()
                .contains("different class systems")
        );
        assert!(resolve(&output, Some(ClassSystem::R6)).is_ok());
    }

    /// An `ExternalPtr<Class>` payload wraps as `Class` in both spellings and
    /// keeps the handle as the Rust return type, like inferred wrapping (#1375).
    #[test]
    fn external_ptr_payload_names_its_class() {
        for (output, attribute, peeled) in [
            (
                "-> WrapAsR6<ExternalPtr<Board>>",
                None,
                "-> ExternalPtr<Board>",
            ),
            (
                "-> ExternalPtr<Board>",
                Some(ClassSystem::R6),
                "-> ExternalPtr<Board>",
            ),
            (
                "-> Option<Vec<WrapAsR6<ExternalPtr<Board>>>>",
                None,
                "-> Option<Vec<ExternalPtr<Board>>>",
            ),
        ] {
            let (plan, output) = resolve(&syn::parse_str(output).unwrap(), attribute).unwrap();
            let expected: ReturnType = syn::parse_str(peeled).unwrap();
            assert_eq!(
                output.to_token_stream().to_string(),
                expected.to_token_stream().to_string()
            );
            assert!(
                plan.unwrap()
                    .r_expression(".val", None)
                    .contains("Board$new(.ptr = ")
            );
        }
    }

    #[test]
    fn explicit_self_and_qualified_targets_do_not_use_registry_placeholders() {
        for (output, target) in [
            ("-> WrapAsR6<Self>", "ActualClass"),
            ("-> WrapAsR6<other::Board>", "Board"),
        ] {
            let (plan, _) = resolve(&syn::parse_str(output).unwrap(), None).unwrap();
            assert_eq!(
                plan.unwrap().r_expression(".val", Some("ActualClass")),
                format!("{target}$new(.ptr = .val)")
            );
        }
    }
}