100 releases (37 breaking)
0.38.4 | Jun 4, 2022 |
---|---|
0.38.0 | May 28, 2022 |
0.34.1 | Sep 25, 2021 |
0.17.0 | Jul 26, 2021 |
0.8.0 | Nov 2, 2020 |
#122 in #derive-debug
225KB
5K
SLoC
dep-obj
Dependency object: effective reactive heterogeneous container.
Example: simple dependency type
The dependency objects system bases on component-arena
.
A component may have multiply dependency objects as its parts. Some of them may be dynamically typed
and/or optional. Lets see an example of simple component with one dependency object of fixed type.
Consider as an example carriable game object Item
.
To describe abstract entity Item
, we will need the following list of types:
- the component data holder
ItemComponent
; - the id of component
Item
; - the dependency object type
ItemProps
; - the components arena
Items
.
First, define the component containing the dependency object:
macro_attr! {
#[derive(Debug, Component!)]
struct ItemComponent {
props: ItemProps,
}
}
Then, to maintain an encapsulation, wrap Id<ItemComponent>
into a newtype:
macro_attr! {
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, NewtypeComponentId!)]
pub struct Item(Id<ItemComponent>);
}
Dependency objects support properties inheritance. The tree structure of objects is defined
by the DepObjId
trait implementation. We do not need inheritance for Item
, and we
can express it and get appropriate «empty» DepObjId
implementation
by marking it with the DetachedDepObjId
trait:
impl DetachedDepObjId for Item { }
All components need be emplaced in an appropriate arena. Lets create it:
#[derive(Debug)]
pub struct Items {
items: Arena<ItemComponent>,
}
An another foundation the dependency object system based on is
the dyn-context
crate.
To make Items
usage more convenient it is worth to mark it as SelfState
,
i.e. a state
containing the only one part, which is Items
itself:
impl SelfState for Items { }
Now we are ready to specify the dependency type itself:
dep_type! {
#[derive(Debug)]
pub struct ItemProps = Item[ItemProps] {
name: Cow<'static, str> = Cow::Borrowed(""),
base_weight: f32 = 0.0,
weight: f32 = 0.0,
equipped: bool = false,
cursed: bool = false,
}
}
Now we have all structures encoded and can write Item
methods.
First, we need a way to construct a new Item
:
pub fn new(state: &mut dyn State) -> Item {
let items: &mut Items = state.get_mut();
items.0.insert(|id| (ItemComponent { props: ItemProps::new_priv() }, Item(id)))
}
The ItemProps::new_priv
is a constructor, generated by the dep_type!
macro.
Next, we need a way to destroy unneeded items:
pub fn drop_self(self, state: &mut dyn State) {
self.drop_bindings_priv(state);
let items: &mut Items = state.get_mut();
items.0.remove(self.0);
}
And now the last, but not least: an indirect definition
of the function providing access to the dependency object in
the props
field:
impl_dep_obj!(Item {
fn<ItemProps>() -> (ItemProps) { Items | .props }
});
The impl_dep_obj
macro also generates the drop_bindigs_priv
method
we used in the drop_self
method earlier.
Lets take a look at our mod items
as a whole:
mod items {
use components_arena::{Arena, Component, NewtypeComponentId, Id};
use dep_obj::{DetachedDepObjId, dep_type, impl_dep_obj};
use dyn_context::{SelfState, State, StateExt};
use macro_attr_2018::macro_attr;
use std::borrow::Cow;
macro_attr! {
#[derive(Debug, Component!)]
struct ItemComponent {
props: ItemProps,
}
}
macro_attr! {
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, NewtypeComponentId!)]
pub struct Item(Id<ItemComponent>);
}
impl DetachedDepObjId for Item { }
impl Item {
pub fn new(state: &mut dyn State) -> Item {
let items: &mut Items = state.get_mut();
items.0.insert(|id| (ItemComponent { props: ItemProps::new_priv() }, Item(id)))
}
pub fn drop_self(self, state: &mut dyn State) {
self.drop_bindings_priv(state);
let items: &mut Items = state.get_mut();
items.0.remove(self.0);
}
}
impl_dep_obj!(Item {
fn<ItemProps>() -> (ItemProps) { Items | .props }
});
#[derive(Debug)]
pub struct Items(Arena<ItemComponent>);
impl SelfState for Items { }
dep_type! {
#[derive(Debug)]
pub struct ItemProps = Item[ItemProps] {
name: Cow<'static, str> = Cow::Borrowed(""),
base_weight: f32 = 0.0,
weight: f32 = 0.0,
equipped: bool = false,
cursed: bool = false,
}
}
}
The things we lack here are Items
constructor, and, unfortunately, destructor.
Adding constructor is straightforward:
impl Items {
pub fn new() -> Items {
Items(Arena::new())
}
}
The destructor however is tricky. The Item::drop_self
method do two things:
first, it drops all bindings item owes, and, second, it removes items from arena.
The second thing would do automatically, but bindings require manual destroying.
Thus we need explicit Items
destructor to correctly drop all Item
s' bindings.
But we cannot just implement Drop
for Items
because we need State
parameter
to call Item::drop_bindings_priv
. Unfortunately, Rust does not support a
linear types concept, which would allow to have parameters in drop
method.
But dyn-context
and components-arena
crates contain some helpful things,
allowing to express such type properties as good as it is possible in Rust for now.
The Arena
implements special trait, Stop
, that is an analogue of Drop
with
State
parameter. Out wrap Items
, however, does not implement it. Lets fix it:
#[derive(Debug, Stop)]
pub struct Items(Arena<ItemComponent>);
A thing, we want Item::stop
function to do, is call drop_bindings_priv
for
every Item
. To tell it, we need to define some struct (lets call it ItemStop
),
and let ItemComponent
uses it to properly «stop» our Item
s. It is easily achieved
with the Component
derive macro stop
parameter:
#[derive(Debug, Component!(stop=ItemStop)]
struct ItemComponent {
props: ItemProps,
}
If we try to compile, we would get an error pointing to the fact, that
the ComponentStop
trait is not implemented for ItemStop
.
So lets implement it:
impl ComponentStop for ItemStop {
with_arena_in_state_part!(Items);
fn stop(&self, state: &mut dyn State, id: Id<ItemComponent>) {
Item(id).drop_bindings_priv(state);
}
}
Thanks to the with_arena_in_state_part
macro, the only function we were need
to implement manually is stop
.
Take a look at out mod items
:
mod items {
use components_arena::{Arena, Component, ComponentStop, NewtypeComponentId, Id, with_arena_in_state_part};
use dep_obj::{DetachedDepObjId, dep_type, impl_dep_obj};
use dyn_context::{SelfState, State, StateExt, Stop};
use macro_attr_2018::macro_attr;
use std::borrow::Cow;
macro_attr! {
#[derive(Debug, Component!(stop=ItemStop))]
struct ItemComponent {
props: ItemProps,
}
}
impl ComponentStop for ItemStop {
with_arena_in_state_part!(Items);
fn stop(&self, state: &mut dyn State, id: Id<ItemComponent>) {
Item(id).drop_bindings_priv(state);
}
}
macro_attr! {
#[derive(Debug, Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, NewtypeComponentId!)]
pub struct Item(Id<ItemComponent>);
}
impl DetachedDepObjId for Item { }
impl Item {
pub fn new(state: &mut dyn State) -> Item {
let items: &mut Items = state.get_mut();
items.0.insert(|id| (ItemComponent { props: ItemProps::new_priv() }, Item(id)))
}
pub fn drop_self(self, state: &mut dyn State) {
self.drop_bindings_priv(state);
let items: &mut Items = state.get_mut();
items.0.remove(self.0);
}
}
impl_dep_obj!(Item {
fn<ItemProps>() -> (ItemProps) { Items | .props }
});
#[derive(Debug, Stop)]
pub struct Items(Arena<ItemComponent>);
impl SelfState for Items { }
impl Items {
pub fn new() -> Items {
Items(Arena::new())
}
}
dep_type! {
#[derive(Debug)]
pub struct ItemProps = Item[ItemProps] {
name: Cow<'static, str> = Cow::Borrowed(""),
base_weight: f32 = 0.0,
weight: f32 = 0.0,
equipped: bool = false,
cursed: bool = false,
}
}
}
For now Item
does not have any meaningful behavior. Lets add some.
pub fn new(state: &mut dyn State) -> Item {
let items: &mut Items = state.get_mut();
let item = items.0.insert(|id| (ItemComponent { props: ItemProps::new_priv() }, Item(id)));
item.bind_weight(state);
item
}
fn bind_weight(self, state: &mut dyn State) {
let weight = Binding3::new(state, (), |(), base_weight, cursed, equipped| Some(
if equipped && cursed { base_weight + 100.0 } else { base_weight }
));
ItemProps::WEIGHT.bind(state, self, weight);
weight.set_source_1(state, &mut ItemProps::BASE_WEIGHT.value_source(self));
weight.set_source_2(state, &mut ItemProps::CURSED.value_source(self));
weight.set_source_3(state, &mut ItemProps::EQUIPPED.value_source(self));
}
With the code above we have created functional dependency between four Item
properties, and now weight
being a function of other three properties
will be updated automatically when any of them changes.
Finally, lets write some test code to make our just built game system work:
fn track_weight(state: &mut dyn State, item: Item) {
let weight = Binding2::new(state, (), |(), name, weight: Option<Change<f32>>|
weight.map(|weight| (name, weight.new))
);
weight.set_target_fn(state, (), |_state, (), (name, weight)| {
println!("\n{name} now weights {weight}.");
});
item.add_binding::<ItemProps, _>(state, weight);
weight.set_source_1(state, &mut ItemProps::NAME.value_source(item));
weight.set_source_2(state, &mut ItemProps::WEIGHT.change_source(item));
}
fn run(state: &mut dyn State) {
let the_item = Item::new(state);
track_weight(state, the_item);
ItemProps::NAME.set(state, the_item, Cow::Borrowed("The Item")).immediate();
println!("\n> the_item.base_weight = 5.0");
ItemProps::BASE_WEIGHT.set(state, the_item, 5.0).immediate();
println!("\n> the_item.cursed = true");
ItemProps::CURSED.set(state, the_item, true).immediate();
println!("\n> the_item.equipped = true");
ItemProps::EQUIPPED.set(state, the_item, true).immediate();
println!("\n> the_item.cursed = false");
ItemProps::CURSED.set(state, the_item, false).immediate();
the_item.drop_self(state);
}
And the really last thing to do: construct State
instance and call run
.
Our system requires State
containing Items
and special arena for bindings.
It can be easily achieved with merge_mut_and_then
method, combining two
state objects into a single one. And, of course, we should not forget to
call Items::stop
at the end:
fn main() {
(&mut Items::new()).merge_mut_and_then(|state| {
run(state);
Items::stop(state);
}, &mut Bindings::new());
}
Example: builders
When you need to setup initial values for just constructed object,
it is boring to call Type::PROP.set(state, ...).immediate()
many times.
The dep-obj
has a tool for avoid it: object builders.
It is very simple to enable it in the project:
impl Item {
with_builder!(ItemProps);
}
This macro declares function build
, which can be used in the following way:
the_item.build(state, |props| props
.name(Cow::Borrowed("The Item"))
.base_weight(5.0)
.cursed(true)
);
Example: dynamically typed dependency object
Lets add some properties, which are not universal for all Item
s.
To do it we need to use another library: downcast-rs
.
Using this crate, lets define base trait for extended properties dependency type:
pub trait ItemObj: Downcast + DepType<Id=Item> { }
impl_downcast!(ItemObj);
We need a new field in the component:
macro_attr! {
#[derive(Debug, Component!(stop=ItemStop))]
struct ItemComponent {
props: ItemProps,
obj: Box<dyn ItemObj>,
}
}
Modified Item
constructor:
pub fn new(state: &mut dyn State, obj: Box<dyn ItemObj>) -> Item {
let items: &mut Items = state.get_mut();
let item = items.0.insert(|id| (ItemComponent {
props: ItemProps::new_priv(),
obj
}, Item(id)));
item.bind_weight(state);
item
}
And the way to access an object (impl_dep_obj
handles
all dirty work including downcasting):
impl_dep_obj!(Item {
fn<ItemProps>() -> (ItemProps) { Items | .props }
fn<ItemObjKey>() -> dyn(ItemObj) { Items | .obj }
});
Base part is done, and we are ready to code ItemObj
specific variants:
mod weapon {
use dep_obj::dep_type;
use dep_obj::binding::Binding3;
use dyn_context::State;
use crate::items::*;
dep_type! {
#[derive(Debug)]
pub struct Weapon = Item[ItemObjKey] {
base_damage: f32 = 0.0,
damage: f32 = 0.0,
}
}
impl ItemObj for Weapon { }
impl Weapon {
#[allow(clippy::new_ret_no_self)]
pub fn new(state: &mut dyn State) -> Item {
let item = Item::new(state, Box::new(Self::new_priv()));
Self::bind_damage(state, item);
item
}
fn bind_damage(state: &mut dyn State, item: Item) {
let damage = Binding3::new(state, (), |(), base_damage, cursed, equipped| Some(
if equipped && cursed { base_damage / 2.0 } else { base_damage }
));
Weapon::DAMAGE.bind(state, item, damage);
damage.set_source_1(state, &mut Weapon::BASE_DAMAGE.value_source(item));
damage.set_source_2(state, &mut ItemProps::CURSED.value_source(item));
damage.set_source_3(state, &mut ItemProps::EQUIPPED.value_source(item));
}
}
}
Dependencies
~5.5MB
~110K SLoC