miniextendr_macros/

match_arg_derive.rs

//! # `#[derive(MatchArg)]` - Enum ↔ R String with `match.arg` Support
//!
//! This module implements the `#[derive(MatchArg)]` macro which generates
//! the `MatchArg` trait implementation for C-style enums, enabling automatic
//! conversion between Rust enums and R character strings with partial matching.
//!
//! ## Tradeoff
//!
//! Without `#[derive(MatchArg)]`, an enum-shaped argument lands in the Rust
//! function as a raw `String` that you match on by hand — invalid values
//! surface as Rust `Err` deep in the body, with no R-side defaulting and no
//! partial matching. `#[derive(MatchArg)]` shifts that work to the wrapper
//! boundary: the generated R wrapper picks up `match.arg`-style **partial
//! string matching** against the enum's variant list, fills in the first
//! variant as the **R-visible default**, and rejects unknown values before
//! the Rust function is even called. The variant list reaches the R side
//! via a write-time placeholder (`MX_MATCH_ARG_CHOICES`) rather than a
//! string baked into the proc macro, so adding a variant only requires
//! re-running the build.
//!
//! ## Usage
//!
//! ```ignore
//! #[derive(Copy, Clone, MatchArg)]
//! enum Mode {
//!     Fast,
//!     Safe,
//!     Debug,
//! }
//!
//! // Generates impl MatchArg for Mode, TryFromSexp for Mode, IntoR for Mode.
//! ```
//!
//! ## Attributes
//!
//! - `#[match_arg(rename = "name")]` - Rename a variant's choice string
//! - `#[match_arg(rename_all = "snake_case")]` - Rename all variants (snake_case, kebab-case, lower, upper)
//! - `#[match_arg(alias = "name")]` - Another spelling of a variant's choice, matched only when
//!   typed in full (`MatchArg::ALIASES`, #1843). Repeatable, variants only, never renamed by
//!   `rename_all`. An alias that is empty, `"NA"`, a choice, given twice, or a prefix of another
//!   variant's choice is a compile error. Every error that lists the choices names it after them
//!   (`(or "name" for "choice")`, #2148); the formal, the usage and the `@param` line don't.
//! - `#[match_arg(alias = "name", listed = false)]` - Keep the aliases of this attribute out of
//!   every error. `listed` applies to the aliases of its own `#[match_arg(...)]` only; one
//!   without an alias, a repeated one, or a value other than `true` / `false` is a compile error.

use proc_macro2::TokenStream;
use quote::quote;
use syn::{Data, DeriveInput, Fields};

use crate::naming::apply_rename_all;

/// Parsed `#[match_arg(...)]` attributes from an enum or variant.
#[derive(Default)]
struct MatchArgAttrs {
    /// Per-variant rename: `#[match_arg(rename = "custom")]`.
    rename: Option<String>,
    /// Enum-level rename-all: `#[match_arg(rename_all = "snake_case")]`.
    /// Applied to all variants that don't have an explicit `rename`.
    rename_all: Option<String>,
    /// Per-variant aliases, in written order: `#[match_arg(alias = "grey")]`,
    /// repeatable. Each literal is kept for the span of its error, with
    /// whether the errors list it (`listed = false` in the same attribute
    /// opts out).
    aliases: Vec<(syn::LitStr, bool)>,
}

/// Parse `#[match_arg(...)]` attributes from a list of `syn::Attribute`.
///
/// Extracts `rename`, `rename_all`, `alias` and `listed` keys. Validates that
/// `rename_all` uses one of the supported modes: `snake_case`, `kebab-case`,
/// `lower`, `upper`. Returns `Err` for unknown attribute keys or unsupported
/// `rename_all` values. `listed = <bool>` applies to every alias of the same
/// `#[match_arg(...)]` (#2148), so it needs one there, once, with a `bool`
/// value. Where `alias` may appear (variants only) is the caller's check.
fn parse_match_arg_attrs(attrs: &[syn::Attribute]) -> syn::Result<MatchArgAttrs> {
    let mut result = MatchArgAttrs::default();

    for attr in attrs {
        if attr.path().is_ident("match_arg") {
            let mut aliases: Vec<syn::LitStr> = Vec::new();
            // The value of this attribute's `listed`, and its key for the
            // span of an error.
            let mut listed: Option<(bool, syn::Path)> = None;
            attr.parse_nested_meta(|meta| {
                if meta.path.is_ident("rename") {
                    let value: syn::LitStr = meta.value()?.parse()?;
                    result.rename = Some(value.value());
                } else if meta.path.is_ident("alias") {
                    aliases.push(meta.value()?.parse()?);
                } else if meta.path.is_ident("listed") {
                    if listed.is_some() {
                        return Err(meta
                            .error("`listed` is given more than once in this #[match_arg(...)]"));
                    }
                    let value: syn::Expr = meta.value()?.parse()?;
                    let syn::Expr::Lit(syn::ExprLit {
                        lit: syn::Lit::Bool(value),
                        ..
                    }) = value
                    else {
                        return Err(syn::Error::new_spanned(
                            value,
                            "expected `listed = true` or `listed = false`",
                        ));
                    };
                    listed = Some((value.value, meta.path.clone()));
                } else if meta.path.is_ident("rename_all") {
                    let value: syn::LitStr = meta.value()?.parse()?;
                    let val = value.value();
                    match val.as_str() {
                        "snake_case" | "kebab-case" | "lower" | "upper" => {}
                        _ => {
                            return Err(meta.error(
                                "unsupported rename_all value; expected one of: \
                                 snake_case, kebab-case, lower, upper",
                            ));
                        }
                    }
                    result.rename_all = Some(val);
                } else {
                    return Err(meta.error(
                        "unknown match_arg attribute; expected `rename`, `rename_all`, \
                         `alias` or `listed`",
                    ));
                }
                Ok(())
            })?;
            if let Some((_, key)) = listed.as_ref().filter(|_| aliases.is_empty()) {
                return Err(syn::Error::new_spanned(
                    key,
                    "`listed` applies to the aliases of its own #[match_arg(...)], and this \
                     one has none: write it next to `alias = \"...\"`",
                ));
            }
            let listed = listed.is_none_or(|(listed, _)| listed);
            result
                .aliases
                .extend(aliases.into_iter().map(|alias| (alias, listed)));
        }
    }

    Ok(result)
}

/// Main entry point for `#[derive(MatchArg)]`.
///
/// Generates three trait implementations:
/// - `impl MatchArg` -- provides `CHOICES` (static string slice), `ALIASES` (from the
///   variants' `alias = "..."`), `from_choice`, `to_choice`
/// - `impl TryFromSexp` -- converts R character scalar to enum variant via `match_arg_from_sexp`
/// - `impl IntoR` -- converts enum variant to R character scalar via `to_choice().into_sexp()`
///
/// `impl IntoR for Vec<Self>` is provided automatically by the blanket
/// `impl<T: MatchArg> IntoR for Vec<T>` in `miniextendr-api::match_arg`,
/// so returning `Vec<EnumName>` from a `#[miniextendr]` function works
/// without any extra code in the user's crate.
///
/// Validates:
/// - Only enums are accepted (not structs or unions)
/// - Generic enums are rejected
/// - At least one variant is required
/// - Only fieldless (C-style) variants are allowed
/// - No duplicate choice names after renaming
/// - No `alias` on the enum itself, and no alias [`check_aliases`] refuses
///
/// Choice names default to variant identifiers, optionally transformed by
/// `#[match_arg(rename_all = "...")]` or overridden per-variant with
/// `#[match_arg(rename = "...")]`.
pub fn derive_match_arg(input: DeriveInput) -> syn::Result<TokenStream> {
    let name = &input.ident;
    let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();

    // Reject generics for v1
    if !input.generics.params.is_empty() {
        return Err(syn::Error::new_spanned(
            &input.generics,
            "#[derive(MatchArg)] does not support generic enums",
        ));
    }

    // Parse enum-level attributes
    let attrs = parse_match_arg_attrs(&input.attrs)?;
    if let Some((alias, _)) = attrs.aliases.first() {
        return Err(syn::Error::new_spanned(
            alias,
            "`alias` names another spelling of one choice: put \
             #[match_arg(alias = \"...\")] on that choice's variant",
        ));
    }

    // Get enum variants
    let variants = match &input.data {
        Data::Enum(data) => &data.variants,
        Data::Struct(_) => {
            return Err(syn::Error::new_spanned(
                &input,
                "#[derive(MatchArg)] can only be applied to enums",
            ));
        }
        Data::Union(_) => {
            return Err(syn::Error::new_spanned(
                &input,
                "#[derive(MatchArg)] can only be applied to enums",
            ));
        }
    };

    if variants.is_empty() {
        return Err(syn::Error::new_spanned(
            &input,
            "#[derive(MatchArg)] requires at least one variant",
        ));
    }

    let mut choice_names = Vec::new();
    let mut variant_idents = Vec::new();
    // (alias literal, index of its variant's choice in `choice_names`,
    // whether the errors list it)
    let mut variant_aliases: Vec<(syn::LitStr, usize, bool)> = Vec::new();

    for variant in variants {
        // Only allow unit variants (fieldless)
        if !matches!(variant.fields, Fields::Unit) {
            return Err(syn::Error::new_spanned(
                variant,
                "#[derive(MatchArg)] only supports fieldless (C-style) enum variants",
            ));
        }

        // Parse variant-level attributes
        let var_attrs = parse_match_arg_attrs(&variant.attrs)?;

        // Determine choice name
        let choice_name = if let Some(r) = var_attrs.rename {
            r
        } else {
            apply_rename_all(
                &crate::naming::ident_name(&variant.ident),
                attrs.rename_all.as_deref(),
            )
        };

        let at = choice_names.len();
        variant_aliases.extend(
            var_attrs
                .aliases
                .into_iter()
                .map(|(alias, listed)| (alias, at, listed)),
        );
        choice_names.push(choice_name);
        variant_idents.push(&variant.ident);
    }

    // Check for duplicate choice names
    {
        let mut seen = std::collections::HashSet::new();
        for (i, name) in choice_names.iter().enumerate() {
            if !seen.insert(name.as_str()) {
                return Err(syn::Error::new_spanned(
                    &variants.iter().nth(i).unwrap().ident,
                    format!("duplicate choice name {:?} in #[derive(MatchArg)]", name),
                ));
            }
        }
    }

    check_aliases(&choice_names, &variant_aliases)?;

    let choice_strs: Vec<&str> = choice_names.iter().map(|s| s.as_str()).collect();
    // In the order of the variants, then as written: the order the errors
    // list them in.
    let alias_entries = variant_aliases.iter().map(|(alias, at, listed)| {
        let alias = alias.value();
        let target = choice_names[*at].as_str();
        if *listed {
            quote! { ::miniextendr_api::match_arg::MatchArgAlias::new(#alias, #target) }
        } else {
            quote! { ::miniextendr_api::match_arg::MatchArgAlias::unlisted(#alias, #target) }
        }
    });

    Ok(quote! {
        impl #impl_generics ::miniextendr_api::match_arg::MatchArg for #name #ty_generics #where_clause {
            const CHOICES: &'static [&'static str] = &[#(#choice_strs),*];
            const ALIASES: &'static [::miniextendr_api::match_arg::MatchArgAlias] =
                &[#(#alias_entries),*];

            fn from_choice(choice: &str) -> ::core::option::Option<Self> {
                match choice {
                    #(#choice_strs => ::core::option::Option::Some(Self::#variant_idents),)*
                    _ => ::core::option::Option::None,
                }
            }

            fn to_choice(self) -> &'static str {
                match self {
                    #(Self::#variant_idents => #choice_strs,)*
                }
            }
        }

        impl #impl_generics ::miniextendr_api::TryFromSexp for #name #ty_generics #where_clause {
            type Error = ::miniextendr_api::SexpError;
            const CHARACTER_ONLY: bool = true;

            fn try_from_sexp(sexp: ::miniextendr_api::SEXP) -> ::core::result::Result<Self, ::miniextendr_api::SexpError> {
                ::miniextendr_api::match_arg_from_sexp(sexp).map_err(::core::convert::Into::into)
            }
        }

        impl #impl_generics ::miniextendr_api::IntoR for #name #ty_generics #where_clause {
            type Error = ::core::convert::Infallible;

            fn try_into_sexp(self) -> ::core::result::Result<::miniextendr_api::SEXP, ::core::convert::Infallible> {
                ::core::result::Result::Ok(self.into_sexp())
            }

            unsafe fn try_into_sexp_unchecked(self) -> ::core::result::Result<::miniextendr_api::SEXP, ::core::convert::Infallible> {
                self.try_into_sexp()
            }

            fn into_sexp(self) -> ::miniextendr_api::SEXP {
                use ::miniextendr_api::match_arg::MatchArg;
                self.to_choice().into_sexp()
            }
        }


    })
}

/// Refuse the aliases `#[match_arg(alias = "...")]` can't have, all at once
/// (one error per bad alias, spanned on its literal): an alias that is empty
/// (`pmatch()` matches `""` to nothing, while the R check's `match()` would
/// map it), `"NA"` (it would read as a missing value), a choice, given twice
/// (on any variant), or a prefix of another variant's choice, since the alias
/// would change what typing it selects. A prefix of its own choice only is
/// harmless. The wrappers writer applies the same
/// rules to a hand-written `MatchArg::ALIASES`
/// (`miniextendr_api::registry::match_arg_aliases_arg`).
fn check_aliases(choices: &[String], aliases: &[(syn::LitStr, usize, bool)]) -> syn::Result<()> {
    let mut errors: Option<syn::Error> = None;
    let mut seen = std::collections::HashSet::new();
    for (lit, at, _) in aliases {
        let alias = lit.value();
        let target = &choices[*at];
        let problem = if alias.is_empty() {
            Some("an alias can't be empty: the empty string matches no choice".to_string())
        } else if alias == "NA" {
            Some("alias \"NA\" would read as a missing value".to_string())
        } else if choices.contains(&alias) {
            Some(format!("alias {alias:?} is already a choice"))
        } else if !seen.insert(alias.clone()) {
            Some(format!("alias {alias:?} is given more than once"))
        } else {
            choices
                .iter()
                .find(|choice| *choice != target && choice.starts_with(alias.as_str()))
                .map(|other| {
                    format!(
                        "alias {alias:?} for {target:?} is a prefix of the choice {other:?}, \
                         so it would change what typing {alias:?} selects"
                    )
                })
        };
        if let Some(problem) = problem {
            let error = syn::Error::new_spanned(lit, problem);
            match errors.as_mut() {
                Some(errors) => errors.combine(error),
                None => errors = Some(error),
            }
        }
    }
    match errors {
        Some(errors) => Err(errors),
        None => Ok(()),
    }
}

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

    #[test]
    fn test_simple_derive() {
        let input: DeriveInput = syn::parse_quote! {
            enum Mode {
                Fast,
                Safe,
                Debug,
            }
        };

        let result = derive_match_arg(input).unwrap();
        let code = result.to_string();
        assert!(code.contains("Fast"));
        assert!(code.contains("Safe"));
        assert!(code.contains("Debug"));
        assert!(code.contains("CHOICES"));
        assert!(code.contains("from_choice"));
        assert!(code.contains("to_choice"));
    }

    #[test]
    fn test_rename_all() {
        let input: DeriveInput = syn::parse_quote! {
            #[match_arg(rename_all = "snake_case")]
            enum Mode {
                FastMode,
                SafeMode,
            }
        };

        let result = derive_match_arg(input).unwrap();
        let code = result.to_string();
        assert!(code.contains("fast_mode"));
        assert!(code.contains("safe_mode"));
    }

    #[test]
    fn test_rename_variant() {
        let input: DeriveInput = syn::parse_quote! {
            enum Priority {
                #[match_arg(rename = "lo")]
                Low,
                #[match_arg(rename = "hi")]
                High,
            }
        };

        let result = derive_match_arg(input).unwrap();
        let code = result.to_string();
        assert!(code.contains("\"lo\""));
        assert!(code.contains("\"hi\""));
    }

    #[test]
    fn test_reject_fields() {
        let input: DeriveInput = syn::parse_quote! {
            enum Bad {
                A(i32),
            }
        };

        let result = derive_match_arg(input);
        assert!(result.is_err());
    }

    #[test]
    fn test_reject_struct() {
        let input: DeriveInput = syn::parse_quote! {
            struct Bad;
        };

        let result = derive_match_arg(input);
        assert!(result.is_err());
    }

    #[test]
    fn test_reject_empty() {
        let input: DeriveInput = syn::parse_quote! {
            enum Empty {}
        };

        let result = derive_match_arg(input);
        assert!(result.is_err());
    }

    #[test]
    fn test_into_r_impl_present() {
        // The derive emits IntoR for the scalar EnumName.
        // Vec<EnumName> IntoR is covered by the blanket impl<T: MatchArg> IntoR for Vec<T>
        // in miniextendr-api — it is NOT emitted by the derive.
        let input: DeriveInput = syn::parse_quote! {
            enum Mode {
                Fast,
                Safe,
                Debug,
            }
        };

        let result = derive_match_arg(input).unwrap();
        let code = result.to_string();
        // Scalar IntoR impl must be present
        assert!(code.contains("IntoR for Mode"));
        // Vec<Mode> IntoR must NOT be emitted by the derive (covered by blanket in miniextendr-api)
        assert!(!code.contains("IntoR for :: std :: vec :: Vec < Mode >"));
        assert!(!code.contains("match_arg_vec_into_sexp"));
    }

    /// `alias = "..."` fills `ALIASES` with (alias, the variant's choice after
    /// renaming) entries in written order, is repeatable, is not renamed by
    /// `rename_all`, and leaves `CHOICES` alone (#1843). An alias is listed
    /// unless its own attribute says `listed = false` (#2148).
    #[test]
    fn test_aliases() {
        let input: DeriveInput = syn::parse_quote! {
            #[match_arg(rename_all = "lower")]
            enum Shade {
                Red,
                #[match_arg(alias = "grey", alias = "Grau")]
                #[match_arg(alias = "gris", listed = false)]
                Gray,
                #[match_arg(rename = "navy", alias = "Blue", listed = true)]
                Blue,
            }
        };
        let code = derive_match_arg(input).unwrap().to_string();
        assert!(
            code.contains(
                r#"const CHOICES : & 'static [& 'static str] = & ["red" , "gray" , "navy"] ;"#
            ),
            "{code}"
        );
        let alias = |kind: &str, alias: &str, choice: &str| {
            format!(
                ":: miniextendr_api :: match_arg :: MatchArgAlias :: {kind} ({alias:?} , {choice:?})"
            )
        };
        let entries = [
            alias("new", "grey", "gray"),
            alias("new", "Grau", "gray"),
            alias("unlisted", "gris", "gray"),
            alias("new", "Blue", "navy"),
        ];
        assert!(
            code.contains(&format!(
                "const ALIASES : & 'static [:: miniextendr_api :: match_arg :: MatchArgAlias] = & [{}] ;",
                entries.join(" , ")
            )),
            "{code}"
        );
        // An alias is not a choice: `from_choice` matches the choices only.
        assert!(!code.contains(r#""grey" => Some"#), "{code}");
    }

    /// Without aliases `ALIASES` is empty.
    #[test]
    fn test_no_aliases() {
        let input: DeriveInput = syn::parse_quote! {
            enum Mode { Fast, Safe }
        };
        let code = derive_match_arg(input).unwrap().to_string();
        assert!(
            code.contains(
                r#"const ALIASES : & 'static [:: miniextendr_api :: match_arg :: MatchArgAlias] = & [] ;"#
            ),
            "{code}"
        );
    }

    /// `listed` qualifies the aliases of its own attribute: one with none, a
    /// repeated one, and a value that is not `true` / `false` are refused.
    #[test]
    fn test_reject_listed() {
        let error = |input: DeriveInput| match derive_match_arg(input) {
            Ok(_) => String::new(),
            Err(e) => e.to_string(),
        };
        let no_alias = "`listed` applies to the aliases of its own #[match_arg(...)], and this \
                        one has none: write it next to `alias = \"...\"`";
        assert_eq!(
            error(syn::parse_quote! {
                enum Shade {
                    #[match_arg(alias = "grey")]
                    #[match_arg(listed = false)]
                    Gray,
                }
            }),
            no_alias
        );
        assert_eq!(
            error(syn::parse_quote! {
                #[match_arg(listed = false)]
                enum Shade { Gray }
            }),
            no_alias
        );
        assert_eq!(
            error(syn::parse_quote! {
                enum Shade {
                    #[match_arg(alias = "grey", listed = false, listed = true)]
                    Gray,
                }
            }),
            "`listed` is given more than once in this #[match_arg(...)]"
        );
        for value in [quote!("false"), quote!(no), quote!(0)] {
            let input: DeriveInput = syn::parse_quote! {
                enum Shade {
                    #[match_arg(alias = "grey", listed = #value)]
                    Gray,
                }
            };
            assert_eq!(
                error(input),
                "expected `listed = true` or `listed = false`",
                "{value}"
            );
        }
    }

    /// The error messages of the aliases the derive refuses, all reported at
    /// once.
    #[test]
    fn test_reject_aliases() {
        let errors = |input: DeriveInput| -> Vec<String> {
            match derive_match_arg(input) {
                Ok(_) => Vec::new(),
                Err(e) => e.into_iter().map(|e| e.to_string()).collect(),
            }
        };
        assert_eq!(
            errors(syn::parse_quote! {
                #[match_arg(rename_all = "lower")]
                enum Shade {
                    #[match_arg(alias = "")]
                    Red,
                    #[match_arg(alias = "NA", alias = "blue", alias = "grey")]
                    Gray,
                    #[match_arg(alias = "grey", alias = "bl")]
                    Blue,
                    #[match_arg(alias = "gr")]
                    Green,
                }
            }),
            [
                "an alias can't be empty: the empty string matches no choice",
                "alias \"NA\" would read as a missing value",
                "alias \"blue\" is already a choice",
                "alias \"grey\" is given more than once",
                "alias \"gr\" for \"green\" is a prefix of the choice \"gray\", \
                 so it would change what typing \"gr\" selects",
            ]
        );
        // A prefix of its own choice only is allowed ("bl" above).
        assert!(
            errors(syn::parse_quote! {
                enum Shade {
                    Red,
                    #[match_arg(alias = "Gr")]
                    Gray,
                }
            })
            .is_empty()
        );
        // Aliases go on variants.
        assert_eq!(
            errors(syn::parse_quote! {
                #[match_arg(alias = "grey")]
                enum Shade { Red, Gray }
            }),
            ["`alias` names another spelling of one choice: put \
              #[match_arg(alias = \"...\")] on that choice's variant"]
        );
    }

    #[test]
    fn test_duplicate_choice_names() {
        let input: DeriveInput = syn::parse_quote! {
            enum Dup {
                #[match_arg(rename = "same")]
                A,
                #[match_arg(rename = "same")]
                B,
            }
        };

        let result = derive_match_arg(input);
        assert!(result.is_err());
    }
}