# VTable Gen

This crate provides macros to generate C++-ABI VTables by defining the structure and vtable layout.
It also supports VTable inheritance and basic class inheritance.

# Examples

Check out `tests.rs`, which is pretty self-explanatory.

# Usage

## Base Structs
- Define a structure that contains virtual functions
- Define a structure for the VTable that exactly matches the name of the structure it belongs to,
followed by `VTable` exactly. Example:
```rs
struct Foo {}
struct FooVTable {}
```
- Mark both the VTable and structure with `#[gen_vtable]`. Any function pointers you include in
the VTable struct will require implementation in an automatically-generated `<name>Virtuals` trait.
Complete Example:
```rs
#[gen_vtable]
struct Foo {}
#[gen_vtable]
struct FooVTable {
    foo: extern "C" fn(this: &Foo) -> u32;
}
impl FooVirtuals for Foo {
    extern "C" fn foo(this: &Foo) -> u32 { todo!() }
}
```
## Derived Structs
- Define structures exactly as with base structures
- Include the attribute `base`. Example:
```rs
#[gen_vtable]
struct Foo {}
#[gen_vtable]
struct FooVTable {}

#[gen_vtable(base = "Foo")]
struct Bar {}
#[gen_vtable(base = "Foo")]
struct BarVTable {}
```

## Constructing Structs with VTables

Constructing structs with VTables is easy. If the struct is default-able, simply derive
`DefaultVTable` instead of `Default`. This will `impl Default`. If the struct isn't default-able,
define some function `fn new(/* args */) -> Self`. Mark the function with `new_with_vtable`,
supplying base structs if necessary as in `Derived Structs`. For the compiler to know the type,
you must either explicitly replace `Self` as the return type with the type itself, or specify
`self_type`. Here's a verbose example:

```rs
// ...
impl Bar {
    #[new_with_vtable(self_type = "Bar")]
    fn new(baz: u32) -> Self {
        Self { baz }
    }
}
```

which is also equivalent to

```rs
// ...
impl Bar {
    #[new_with_vtable]
    fn new(baz: u32) -> Bar {
        Self { baz }
    }
}
```

If there is a base struct that requires its `new` function to be called, you will have to also
explicitly initialize a `base_with_vtbl` member with the `new` constructor of the child type.
For example:

```rs
// ...
impl Bar {
    #[new_with_vtable(base = "Foo", self_type = "Bar")]
    fn new(baz: u32) -> Self {
        Self {
            base_with_vtable: Foo::new(123),
            baz
        }
    }
}
```

## Overriding Functions

Overriding functions is easy. Because all functions are defined in Traits, one can specify for the
compiler to not generate implementations for base struct `Virtuals` with the argument `no_base_trait_impl`
on the VTable (or both for symmetry :)).
Example:

```rs
// ...
#[gen_vtable(base = "Foo", no_base_trait_impl)]
struct BarVTable {}
// ...
impl FooVirtuals for Bar {
    extern "C" fn some_fn(this: &Foo) {
        // ...
    }
}
```

The only caveat is you will have to implement *all* base traits.

## Automatic Implementation

For an automatic implementation, in the case of some abstract struct for example, simply supply `unimpl`
as an argument to `gen_vtable`, and all methods will be implemented with `unimplemented!()`. Example:

```rs
// ...
#[gen_vtable(unimpl)]
struct Foo {}
#[gen_vtable(unimpl)]
struct FooVTable {}

// `FooVirtuals` is implemented for `Foo`
```

# Known Limitations
- `vtable_gen` currently does not support generic structs. This is a trivial addition, however, and
will likely be added in the future