templatia_derive/

lib.rs

#![forbid(unsafe_code)]
//! # Templatia Derive
//!
//! Procedural macros for the templatia template parsing library.
//!
//! This crate provides the `#[derive(Template)]` macro that automatically generates
//! `templatia::Template` trait implementations for named structs.
//!
//! ## Limitations
//!
//! - **Named Structs Only**: Currently only `struct Name { field: Type }` is supported
//! - **No Tuple Structs**: `struct Point(i32, i32)` is not supported yet
//! - **No Enums**: Enum support is planned for future versions
//! - **Field Requirements**: Template fields must implement `Display`, `FromStr`, and `PartialEq`
//!
//! ## Attribute Reference
//!
//! ### `#[templatia(template = "...")]`
//!
//! Defines a custom template string with `{field_name}` placeholders.
//!
//! **Rules:**
//! - Placeholders must match struct field names exactly
//! - All placeholders must reference existing fields
//! - Duplicate placeholders are allowed but must have consistent values during parsing
//!
//! For detailed usage examples and comprehensive documentation, see the main `templatia` crate.

pub(crate) mod error;
pub(crate) mod fields;
mod inv;
mod parser;
mod render;
mod utils;

use crate::error::generate_unsupported_compile_error;
use crate::fields::{FieldKind, Fields};
use crate::parser::{TemplateSegments, parse_template};
use crate::render::generate_format_string_args;
use darling::FromDeriveInput;
use darling::util::{Flag, Override};
use inv::generator::generate_str_parser;
use proc_macro::TokenStream;
use quote::quote;
use std::collections::HashSet;
use syn::{DeriveInput, parse_macro_input};

#[derive(Debug, FromDeriveInput)]
#[darling(attributes(templatia), supports(struct_named))]
struct TemplateOpts {
    /// The target struct identifier.
    ident: syn::Ident,
    /// All fields of the target struct.
    data: darling::ast::Data<(), syn::Field>,
    /// Optional template string provided via `#[templatia(template = "...")]`.
    #[darling(default)]
    template: Override<String>,
    #[darling(default)]
    allow_missing_placeholders: Flag,
    #[darling(default)]
    empty_str_option_not_none: Flag,
}

/// Derive macro for implementing `templatia::Template` trait on named structs.
///
/// This procedural macro automatically generates `Template` trait implementations,
/// enabling bidirectional conversion between structs and template strings.
///
/// # Type Requirements
///
/// All fields referenced in the template must implement:
/// - `std::fmt::Display` for serialization (`render_string`)
/// - `std::str::FromStr` for deserialization (`from_str`)
/// - `std::cmp::PartialEq` for consistency validation with duplicate placeholders
///
/// # Compilation Errors
///
/// The macro will produce compile-time errors in the following cases:
/// - Template references non-existent struct fields
/// - Template parsing fails due to invalid syntax
/// - Applied to unsupported struct types (tuple structs, unit structs, enums)
/// - Field types don't satisfy the required trait bounds
#[proc_macro_derive(Template, attributes(templatia))]
pub fn template_derive(input: TokenStream) -> TokenStream {
    let ast = parse_macro_input!(input as DeriveInput);

    let opts = match TemplateOpts::from_derive_input(&ast) {
        Ok(opts) => opts,
        Err(e) => return e.write_errors().into(),
    };

    let name = &opts.ident;

    let template = match &opts.template {
        Override::Explicit(template) => template.to_string(),
        Override::Inherit => {
            if let syn::Data::Struct(data_struct) = &ast.data {
                if let syn::Fields::Named(fields_named) = &data_struct.fields {
                    fields_named
                        .named
                        .iter()
                        .filter_map(|field| field.ident.as_ref())
                        .map(|ident| format!("{0} = {{{0}}}", ident.to_string()))
                        .collect::<Vec<_>>()
                        .join("\n")
                } else {
                    String::new()
                }
            } else {
                String::new()
            }
        }
    };

    let marker_input = format!("{}::{}", name, template);
    let hash = {
        use std::hash::{DefaultHasher, Hash, Hasher};

        let mut hasher = DefaultHasher::new();
        marker_input.hash(&mut hasher);

        hasher.finish()
    };
    let escaped_colon_marker = format!("<escaped_colon_templatia_{:x}>", hash);

    let allow_missing_placeholders = opts.allow_missing_placeholders.is_present();
    let empty_str_as_none = opts.empty_str_option_not_none.is_present();

    let all_fields = if let darling::ast::Data::Struct(data_struct) = &opts.data {
        &data_struct.fields
    } else {
        // Currently, this crates supports only named struct so this branch is unreachable.
        unreachable!()
    };

    let fields = Fields::new(all_fields);

    let option_fields = fields
        .option_fields()
        .keys()
        .copied()
        .collect::<HashSet<_>>();

    let segments = match parse_template(&template) {
        Ok(segments) => segments,
        Err(e) => {
            let error =
                syn::Error::new_spanned(&opts.ident, format!("Failed to parse template: {}", e));
            // Transform syn::Error to TokenStream, and fast return
            return error.to_compile_error().into();
        }
    };

    let (format_string, format_args) = generate_format_string_args(&segments, &option_fields);

    // Gathering the all placeholder name without duplication
    let placeholder_names = segments
        .iter()
        .filter_map(|segment| {
            if let TemplateSegments::Placeholder(name) = segment {
                Some(name.trim().to_string())
            } else {
                None
            }
        })
        .collect::<HashSet<_>>();

    let str_from_parser = generate_str_parser(
        name,
        &fields,
        &placeholder_names,
        &segments,
        allow_missing_placeholders,
        !empty_str_as_none,
        &escaped_colon_marker,
    );

    // Generate trait bound
    let (impl_generics, ty_generics, where_clause) = ast.generics.split_for_impl();

    let mut new_where_clause = where_clause
        .cloned()
        .unwrap_or_else(|| syn::parse_quote! { where });

    for field in fields.used_fields_in_template(&placeholder_names) {
        if let Some(ident) = field.ident.as_ref() {
            match fields.get_field_kind(ident) {
                Some(FieldKind::Option(ty)) => {
                    new_where_clause.predicates.push(syn::parse_quote! {
                        #ty: ::std::fmt::Display + ::std::str::FromStr + ::std::cmp::PartialEq
                    });
                    new_where_clause.predicates.push(syn::parse_quote! {
                        <#ty as ::std::str::FromStr>::Err: ::std::fmt::Display
                    });
                }
                Some(FieldKind::Primitive(ty)) => {
                    if !allow_missing_placeholders {
                        new_where_clause.predicates.push(syn::parse_quote! {
                            #ty: ::std::fmt::Display + ::std::str::FromStr + ::std::cmp::PartialEq
                        });
                    } else {
                        new_where_clause.predicates.push(syn::parse_quote! {
                            #ty: ::std::fmt::Display + ::std::str::FromStr + ::std::cmp::PartialEq + ::std::default::Default
                        });
                    }
                    new_where_clause.predicates.push(syn::parse_quote! {
                        <#ty as ::std::str::FromStr>::Err: ::std::fmt::Display
                    });
                }
                Some(kind) => return generate_unsupported_compile_error(ident, kind).into(),
                None => {
                    return generate_unsupported_compile_error(ident, &FieldKind::Unknown).into();
                }
            }
        }
    }

    let where_clause = if new_where_clause.predicates.is_empty() {
        quote! {}
    } else {
        quote! { #new_where_clause }
    };

    let replace_escaped_to_colon = quote! { replace(#escaped_colon_marker, ":") };

    quote! {
        impl #impl_generics ::templatia::Template for #name #ty_generics #where_clause {
            type Error = templatia::TemplateError;

            fn render_string(&self) -> String {
                format!(#format_string, #(#format_args),*)
            }

            fn from_str(s: &str) -> Result<Self, Self::Error> {
                use ::templatia::__private::chumsky;
                use ::templatia::__private::chumsky::Parser;
                use ::templatia::__private::chumsky::prelude::*;

                let parser = #str_from_parser;
                match parser.parse(s).into_result() {
                    Ok(value) => Ok(value),
                    Err(errs) => {
                        for err in &errs {
                            if let ::templatia::__private::chumsky::error::RichReason::Custom(msg) = err.reason() {
                                let m = msg.to_string();
                                const PFX_CONFLICT: &str = "__templatia_conflict__:";
                                const PFX_PARSE: &str = "__templatia_parse_type__:";
                                const PFX_PARSE_LITERAL: &str = "__templatia_parse_literal__:";
                                if let Some(rest) = m.strip_prefix(PFX_CONFLICT) {
                                    if let Some((placeholder, rest)) = rest.split_once("::") {
                                        if let Some((first_value, second_value)) = rest.split_once("::") {
                                            return Err(::templatia::TemplateError::InconsistentValues {
                                                placeholder: placeholder.#replace_escaped_to_colon.to_string(),
                                                first_value: first_value.#replace_escaped_to_colon.to_string(),
                                                second_value: second_value.#replace_escaped_to_colon.to_string(),
                                            });
                                        }
                                    }
                                } else if let Some(rest) = m.strip_prefix(PFX_PARSE) {
                                    if let Some((placeholder, rest)) = rest.split_once("::") {
                                        if let Some((value, ty)) = rest.split_once("::") {
                                            return Err(::templatia::TemplateError::ParseToType {
                                                placeholder: placeholder.#replace_escaped_to_colon.to_string(),
                                                value: value.#replace_escaped_to_colon.to_string(),
                                                type_name: ty.#replace_escaped_to_colon.to_string(),
                                            })
                                        }
                                    }
                                } else if let Some(rest) = m.strip_prefix(PFX_PARSE_LITERAL) {
                                    if let Some((expected, got)) = rest.split_once("::") {
                                        let expected_next_literal = expected.trim_matches('"')
                                            .#replace_escaped_to_colon
                                            .to_string();
                                        let remaining_text = got.#replace_escaped_to_colon.to_string();

                                        return Err(::templatia::TemplateError::UnexpectedInput {
                                            expected_next_literal,
                                            remaining_text,
                                        })
                                    }
                                }
                            }
                        }

                        let error_message = errs.into_iter()
                            .map(|err| err.to_string())
                            .collect::<Vec<_>>()
                            .join("\n");

                        Err(templatia::TemplateError::Parse(error_message))
                    }
                }
            }
        }
    }.into()
}