hereditary

Crates.iohereditary
lib.rshereditary
version0.1.0
sourcesrc
created_at2023-07-28 21:49:48.407479
updated_at2023-07-28 21:49:48.407479
descriptionProcedural macros for emulating OOP Inheritance in Rust
homepage
repositoryhttps://github.com/datapture/hereditary
max_upload_size
id928911
size198,526
Francisco Leon (superoptimo)

documentation

README

Hereditary

Procedural macros for emulating OOP Inheritance in Rust, by extending the trait functionality in structs based on their composition (as they contain instances of other types that implement the desired functionality).

Composition Over Inheritance

Hereditary generates the boilerplate of trait implementations for the composited struct, by Forwarding the required methods that wrap the functionality already implemented in the contained instances referenced by its struct fields.

Currently, Hereditary support 2 kinds of delegation:

  • Partial Delegation: By using the decorator attribute #[forward_trait(submember)] on trait implementations.
  • Full Delegation: By applying #[derive(Forwarding)] on the composited struct, it derives the trait implementation on the struct field (designated by attribute #[forward_derive(Trait)]).

Note

Learn more in the documentation page here https://docs.rs/hereditary

Features

  • Brings subtype polymorphism on composite structs with just one instruction, vesting the new type with the same interface as its components.
  • Re-use fields/method implementations from other types as subcomponents, without needing to repeately write wrapping code that forwards the methods of those subcomponents.
  • Hereditary tools are essentially zero-cost abstractions. They doesn't require runtime structures for holding trait type information. All the work it's done by macros and code generation.
  • Embrace the New Type pattern effectively, but without the previous awkward issues of having to re-implement the inner-type interfaces for the new-type. By using this technique Rust programmers avoid the problems of incorporating new behaviour of existing foreign types, bypassing the Orphan Rule for traits.

Usage

Install in your repository:

cargo add hereditary

Insert hereditary macros in your code:

mod animal {
    // Attribute macro for generating trait info
    #[hereditary::trait_info]
    pub trait Cannis {
        fn bark(&self)-> String;
        fn sniff(&self)-> bool; 
    }
    #[hereditary::trait_info]
    pub trait Bird {
       fn sing(&self) -> String;
       fn fly(&mut self, elevation:f64) -> f64; 
    }
}

// Heritance for an hybrid animal
#[derive(hereditary::Forwarding)]
struct KimeraSphinx 
{    
    #[forward_derive(animal::Cannis)] // full implementation of Cannis
    dogpart:Bulldog,
    birdpart:Seagull
}

// Combining existing trait implementation from Seagull instance
#[hereditary::forward_trait(birdpart)]
impl animal::Bird for KimeraSphinx
{
    fn sing(&self) -> String
    {
        self.dogpart.bark()
    }
}

// -- Subcomponent implementations -- //
struct Bulldog { position:f64 }
impl animal::Cannis for Bulldog { 
    //... Cannis methods ...
}
struct Seagull {  elevation:f64 }
impl animal::Bird for Seagull {
     //... Bird methods ...
}

fn main() {
    // Instance kimera
    let mut kimera = KimeraSphinx::new();
    // A dogs that flies.
    assert_eq!(kimera.fly(50f64), 50f64);
    assert_eq!(kimera.bark(), kimera.sing()); // It barks instead of singing
    assert_eq!(kimera.sniff(), true);
}

Limitations

  • Because of the heavily usage of macros, code made with Hereditary would incurr in longer compilation processes.
  • Sometimes, the traits information cannot be referenced by external modules, because trait_info generated macros aren't imported automatically as same as their corresponding traits. That's why they need to be referenced with the full path in the forwarding attributes (animal::Bird), instead of just Bird. This is a known issue related with declarative macros and the scope rules for their visibibility, as they have special needs when exporting them as module symbols.

License

Apache 2.0

Authors: Francisco Leon

Commit count: 9

cargo fmt