derive_defs/

lib.rs

//! # derive-defs
//!
//! Library for generating derive preset macros from TOML configuration.
//!
//! This crate provides functionality to parse TOML configuration files
//! and generate proc-macro code for derive attribute presets.
//!
//! ## Overview
//!
//! `derive-defs` allows you to define named sets of derive attributes
//! through a declarative TOML configuration. This is useful when you have
//! common derive patterns that you use repeatedly across your codebase.
//!
//! ## Quick Start
//!
//! 1. Create a `derive_defs.toml` configuration file:
//!
//! ```toml
//! [defs.serialization]
//! traits = ["Clone", "Serialize", "Deserialize"]
//! attrs = ['#[serde(rename_all = "camelCase")]']
//!
//! [defs.model]
//! traits = ["Debug", "Clone", "PartialEq"]
//! ```
//!
//! 2. Add to your `build.rs`:
//!
//! ```rust,no_run
//! derive_defs::generate("derive_defs.toml")
//!     .expect("Failed to generate derive defs");
//! ```
//!
//! 3. Use the generated macros in your code:
//!
//! ```rust,ignore
//! use my_crate_macros::*;
//!
//! #[serialization]
//! struct User {
//!     name: String,
//!     age: u32,
//! }
//! ```
//!
//! ## Features
//!
//! - **Declarative Configuration**: Define derive presets in TOML, not code
//! - **Inheritance**: Bundles can extend other bundles via `extends`
//! - **Cross-file Imports**: Split configuration across multiple files
//! - **Runtime Modification**: Use `omit`/`add` to modify bundles at use site
//!
//! ## TOML Configuration
//!
//! ### Basic Syntax
//!
//! ```toml
//! [defs.<name>]
//! traits = ["Trait1", "Trait2"]  # List of derive traits
//! attrs = ["#[attr]"]             # Additional attributes
//! extends = "<parent>"            # Inheritance (optional)
//! ```
//!
//! ### Inheritance
//!
//! ```toml
//! [defs.base]
//! traits = ["Debug", "Clone"]
//!
//! [defs.value_object]
//! extends = "base"
//! traits = ["PartialEq", "Eq", "Hash"]
//! # Result: Debug, Clone, PartialEq, Eq, Hash
//! ```
//!
//! ### Cross-file Imports
//!
//! ```toml
//! [includes]
//! common = "shared/common_defs.toml"
//!
//! [defs.api_response]
//! extends = "common.serialization"
//! traits = ["Default"]
//! ```
//!
//! ## API Usage
//!
//! ### Attribute Modifiers
//!
//! ```rust,ignore
//! // Basic usage
//! #[serialization]
//! struct User { ... }
//!
//! // Exclude Clone from the bundle
//! #[serialization(omit(Clone))]
//! struct Session { ... }
//!
//! // Add Default and Hash to the bundle
//! #[serialization(add(Default, Hash))]
//! struct Config { ... }
//!
//! // Exclude serde attributes
//! #[serialization(omit_attrs(serde))]
//! struct Internal { ... }
//!
//! // Combination
//! #[serialization(omit(Clone), add(Copy))]
//! struct Flags { ... }
//! ```
//!
//! ## Error Handling
//!
//! The crate provides clear error messages at `build.rs` time:
//!
//! - Circular inheritance detection
//! - Undefined parent references
//! - Missing include files
//! - Duplicate definition names

#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc(
    html_logo_url = "https://raw.githubusercontent.com/opentc/rust-derive-defs/main/assets/logo.png"
)]
#![doc(
    html_favicon_url = "https://raw.githubusercontent.com/opentc/rust-derive-defs/main/assets/favicon.ico"
)]

use std::path::Path;

pub mod codegen;
pub mod includes;
pub mod parser;
pub mod resolver;
pub mod validation;

/// Errors that can occur during code generation.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
    /// Failed to read the configuration file.
    #[error("failed to read config file: {0}")]
    ConfigRead(#[source] std::io::Error),

    /// Failed to parse TOML.
    #[error("failed to parse TOML: {0}")]
    TomlParse(#[source] toml::de::Error),

    /// Validation error.
    #[error("validation error: {0}")]
    Validation(String),

    /// Failed to write generated code.
    #[error("failed to write generated code: {0}")]
    CodegenWrite(#[source] std::io::Error),

    /// Circular dependency detected.
    #[error("circular extends detected: {0}")]
    CircularDependency(String),

    /// Reference to undefined definition.
    #[error("def \"{def}\" extends \"{parent}\" which is not defined")]
    UndefinedParent {
        /// The name of the definition with the invalid extends.
        def: String,
        /// The name of the undefined parent.
        parent: String,
    },

    /// Include file not found.
    #[error("include file \"{path}\" not found (resolved to {resolved})")]
    IncludeNotFound {
        /// The path as specified in the config.
        path: String,
        /// The resolved absolute path.
        resolved: String,
    },
}

/// Result type alias for this crate.
pub type Result<T> = std::result::Result<T, Error>;

/// Generate proc-macro code from a TOML configuration file.
///
/// This function parses the TOML configuration at `path` and generates
/// proc-macro code in the `OUT_DIR` directory. The generated code should
/// be included in your proc-macro crate.
///
/// # Errors
///
/// Returns an error if:
/// - The configuration file cannot be read
/// - The TOML is invalid
/// - There are validation errors (circular dependencies, undefined parents, etc.)
/// - The output file cannot be written
///
/// # Example
///
/// ```no_run
/// derive_defs::generate("derive_defs.toml")
///     .expect("Failed to generate derive defs");
/// ```
///
/// # Panics
///
/// This function panics if the `OUT_DIR` environment variable is not set.
/// This should only happen if called outside of a build script context.
pub fn generate<P: AsRef<Path>>(path: P) -> Result<()> {
    let config = parser::parse_file(&path)?;
    let config = includes::resolve_includes(config, &path)?;
    let resolved = resolver::resolve(&config)?;
    codegen::generate(resolved)
}

/// Generate proc-macro code from a TOML configuration file with custom output path.
///
/// Similar to [`generate`], but allows specifying a custom output path instead
/// of using `OUT_DIR`.
///
/// # Errors
///
/// Same as [`generate`].
///
/// # Example
///
/// ```no_run
/// derive_defs::generate_to("derive_defs.toml", "/tmp/output.rs")
///     .expect("Failed to generate derive defs");
/// ```
pub fn generate_to<P: AsRef<Path>, O: AsRef<Path>>(path: P, output: O) -> Result<()> {
    let config = parser::parse_file(&path)?;
    let config = includes::resolve_includes(config, &path)?;
    let resolved = resolver::resolve(&config)?;
    codegen::generate_to(resolved, output)
}

/// Generate proc-macro code from an already resolved configuration.
///
/// This is useful when you want to programmatically build a configuration
/// and generate code without reading from a file.
///
/// # Errors
///
/// Returns an error if writing the output file fails.
///
/// # Example
///
/// ```no_run
/// use derive_defs::resolver::{ResolvedConfig, ResolvedDef};
/// use std::collections::HashMap;
///
/// let mut defs = HashMap::new();
/// defs.insert("model".to_string(), ResolvedDef {
///     name: "model".to_string(),
///     traits: vec!["Debug".to_string(), "Clone".to_string()],
///     attrs: vec![],
/// });
///
/// let config = ResolvedConfig { defs };
/// derive_defs::generate_from_resolved(config, "/tmp/output.rs").unwrap();
/// ```
pub fn generate_from_resolved<O: AsRef<Path>>(
    resolved: resolver::ResolvedConfig,
    output: O,
) -> Result<()> {
    codegen::generate_to(resolved, output)
}

/// Common imports for convenience.
pub mod prelude {
    pub use crate::{Error, Result, generate, generate_to};
}