gltf-v1-derive

Procedural macros for glTF 1.0 validation

Derive macros for validation and serialization traits

:book: Table of Contents

:pencil: About The Crate

gltf-v1-derive provides procedural macro support for glTF 1.0 validation and serialization. This crate is part of the asset-importer-rs project and provides the necessary derive macros for implementing validation and serialization traits, enabling automatic code generation for glTF 1.0 data structures.

This crate provides the essential functionality for:

• Validation Derive - Automatic implementation of validation traits
• Custom Validation Hooks - Extensible validation through attributes
• Field Validation - Automatic field validation generation
• Nested Structure Support - Complex structure validation
• Path-based Error Reporting - Detailed error location tracking
• Procedural Macro Support - Rust code generation and parsing

:cloud: Features

• Validate Derive Macro - Automatic validation trait implementation
• Custom Validation Hooks - Extensible validation through attributes
• Automatic Field Validation - Generated validation code for each field
• Nested Structure Support - Complex nested structure validation
• Path-based Error Reporting - Detailed error location and context
• Procedural Macro Support - Rust code parsing and generation
• String Case Conversion - Automatic case conversion utilities
• Token Stream Generation - Efficient code generation

:floppy_disk: Main Components

Derive Macros

• Validate - Main validation trait derive macro
• Custom Validation Hooks - Attribute-based validation extension
• Field Validation - Automatic field-level validation
• Nested Validation - Complex structure validation support

Procedural Macro Features

• Code Parsing - Rust code structure analysis
• Token Generation - Efficient code generation
• Attribute Processing - Custom attribute handling
• Error Reporting - Compile-time error generation

Validation System

• Automatic Implementation - Trait implementation generation
• Custom Hooks - Extensible validation system
• Path Tracking - Error location reporting
• Type Safety - Compile-time validation checks

:book: Getting Started

Add the following to your Cargo.toml:

[dependencies]
gltf-v1-derive = "0.3.0"

# Or for development from source:
gltf-v1-derive = { path = "../path/to/gltf-v1-derive" }

:small_orange_diamond: Usage Examples

Basic validation derive example:

use gltf_v1_derive::Validate;

#[derive(Validate)]
struct MyStruct {
    field1: String,
    field2: i32,
}

// The Validate trait is automatically implemented
let my_struct = MyStruct {
    field1: "test".to_string(),
    field2: 42,
};

// Validation can be called automatically
my_struct.validate(&root, &path, &mut report)?;

Custom validation hook example:

use gltf_v1_derive::Validate;

#[derive(Validate)]
#[gltf(validate_hook = "custom_validate")]
struct CustomStruct {
    field1: String,
    field2: i32,
}

fn custom_validate(
    this: &CustomStruct,
    root: &Root,
    path: impl Fn() -> Path,
    report: &mut impl FnMut(&dyn Fn() -> Path, Error),
) {
    // Custom validation logic
    if this.field2 < 0 {
        report(&path, Error::InvalidValue("field2 must be positive"));
    }
}

Nested structure validation:

use gltf_v1_derive::Validate;

#[derive(Validate)]
struct ParentStruct {
    child: ChildStruct,
    name: String,
}

#[derive(Validate)]
struct ChildStruct {
    value: f32,
    #[gltf(validate_hook = "validate_range")]
    range: i32,
}

fn validate_range(
    this: &i32,
    _root: &Root,
    path: impl Fn() -> Path,
    report: &mut impl FnMut(&dyn Fn() -> Path, Error),
) {
    if *this < 0 || *this > 100 {
        report(&path, Error::InvalidValue("range must be between 0 and 100"));
    }
}

:gear: Implementation Details

The crate provides comprehensive procedural macro support for glTF 1.0 validation and serialization, enabling automatic code generation and trait implementation.

Validation Derive Features

• Automatic Trait Implementation - Generates Validate trait implementations
• Field-level Validation - Automatic validation code for each field
• Custom Validation Hooks - Extensible validation through attributes
• Nested Structure Handling - Complex structure validation support
• Path-based Error Reporting - Detailed error location tracking

Procedural Macro Capabilities

• Rust Code Parsing - AST analysis and structure understanding
• Token Stream Generation - Efficient code generation
• Attribute Processing - Custom attribute handling and validation
• Compile-time Validation - Early error detection and reporting

:small_orange_diamond: Dependencies

Core Dependencies

• proc-macro2 - Procedural macro support
• quote - Token stream generation
• syn - Rust code parsing
• inflections - String case conversion utilities

Procedural Macro Support

• proc-macro = true - Enables procedural macro functionality

:warning: Internal Use

This crate is primarily intended for internal use within the asset-importer-rs project, specifically for the glTF 1.0 implementation. It provides the necessary derive macros for implementing validation and serialization traits that are used throughout the glTF 1.0 ecosystem.

While the crate can be used independently, it is designed and optimized for use within the asset-importer-rs workspace and may have dependencies on internal types and traits specific to the project.

:scroll: License

This project is part of the asset-importer-rs workspace and follows its licensing terms. See the main project LICENSE file for details.

Copyright (c) 2024 Jackson Levitt