ez_tui/core/

port.rs

use crate::types::args::EzArgs;
use crate::types::event::EzMsg;
use crate::types::ship_ids::{EzShipId, EzShipIds};
use crate::types::state::EzState;
use crate::{AttrValue, Attribute, BoxedShip, Error, EzCptIds, EzEvent, Result, Sender, State};
use displaydoc::Display;
use hashlink::LinkedHashMap;
use std::fmt::Debug;
use tracing::warn;

/// A ship is a struct that can be subscribed to some events; execute some - probably async - code; and emit events.
/// It is used if your app is dependent on some api calls, or other IO operations, they'll certainly have to be done done via a Ship.
///
//FEAT: when unregistering follow same principle as View
/// # Examples
/// ```
//DOC : Add a basic demo with ship and include it here
/// ```
pub trait Ship<CID, CA, CS, CM>: Debug
where
    CID: EzCptIds,
    CA: EzArgs,
    CS: EzState,
    CM: EzMsg,
{
    /// Method to implement to handle events.
    /// The ship will receive only events it is subscribed to.
    #[allow(unused_variables)]
    fn on_event(
        &mut self,
        event: EzEvent<CID, CM>,
        state: &mut State<CS>,
    ) -> Vec<EzEvent<CID, CM>> {
        vec![]
    }

    /// Method called on first tick.
    #[allow(unused_variables)]
    fn init(&mut self, state: &mut State<CS>) -> Vec<EzEvent<CID, CM>> {
        vec![]
    }

    /// Method called on every tick. You should implement it only if you need to save a reference to the state or if your business logic needs to execute some code on a regular basis.
    #[allow(unused_variables)]
    fn tick(&mut self, state: &mut State<CS>) -> Vec<EzEvent<CID, CM>> {
        vec![]
    }

    /// The method called when the ship is mounted to save the [`Sender`] channel
    fn set_tx(&mut self, msg_tx: Sender<EzEvent<CID, CM>>);
}

/// The errors that could happen when using the [`Port`]
#[derive(Debug, Display, Eq, PartialEq, Clone, PartialOrd)]
pub enum PortError {
    /// ship already registered
    ShipAlreadyRegistered,
    /// ship not found
    ShipNotFound,
}

/// The port is the struct that holds all your ships. Like the [`View`], you'll only have one port in your app but as many ships as you want.
/// Again like the [`View`], the port is the orchestrator of your ships. It will send the forward to/from the ships and your app.
#[derive(Debug)]
pub struct Port<CID, SID, CA, CS, CM>
where
    SID: EzShipIds,
    CA: EzArgs,
    CS: EzState,
    CM: EzMsg,
{
    ships: LinkedHashMap<EzShipId<SID>, BoxedShip<CID, CA, CS, CM>>,
}

impl<CID, SID, CA, CS, CM> Default for Port<CID, SID, CA, CS, CM>
where
    CID: EzCptIds,
    SID: EzShipIds,
    CA: EzArgs,
    CS: EzState,
    CM: EzMsg,
{
    fn default() -> Self {
        Self {
            ships: LinkedHashMap::new(),
        }
    }
}

// Public interface
impl<CID, SID, CA, CS, CM> Port<CID, SID, CA, CS, CM>
where
    CID: EzCptIds,
    SID: EzShipIds,
    CA: EzArgs,
    CS: EzState,
    CM: EzMsg,
{
    /// Initialize a new empty port
    pub fn init(&mut self, tx: &Sender<EzEvent<CID, CM>>) {
        for (_, ship) in &mut self.ships {
            ship.set_tx(tx.clone());
        }
    }
    /// Add a new ship to the port
    ///
    /// # Errors
    /// * [`PortError::ShipAlreadyRegistered`] if that ship ID is already present in the port
    pub fn register(&mut self, id: SID, ship: BoxedShip<CID, CA, CS, CM>) -> Result<()> {
        self.register_internal(id.into(), ship)
    }

    /// Remove the ship with given id from the port
    ///
    /// # Errors
    /// * [`PortError::ShipNotFound`] if there is no ship with that id in the port
    pub fn unregister(&mut self, id: &SID) -> Result<()> {
        self.unregister_internal(&id.clone().into())
    }

    /// Check if the ship with given id is registered in the port
    pub fn registered(&self, id: &SID) -> bool {
        self.registered_internal(&id.clone().into())
    }

    /// Query a component for an attribute
    //FIXME: If we keep Attribute concept, we should integrate it to ships
    /// # Errors
    /// None  for now
    pub fn query_ship(&self, _: &EzShipId<SID>, _: Attribute) -> Result<Option<AttrValue>> {
        Ok(None)
    }

    /// Set an attribute to a component
    //FIXME: If we keep Attribute concept, we should integrate it to ships
    /// # Errors
    /// None  for now
    pub fn set_ship_attr(&mut self, _: &EzShipId<SID>, _: Attribute, _: AttrValue) -> Result<()> {
        Ok(())
    }
}
// Crate specific interface
impl<CID, SID, CA, CS, CM> Port<CID, SID, CA, CS, CM>
where
    CID: EzCptIds,
    SID: EzShipIds,
    CA: EzArgs,
    CS: EzState,
    CM: EzMsg,
{
    pub(crate) fn forward(
        &mut self,
        id: &EzShipId<SID>,
        event: EzEvent<CID, CM>,
        state: &mut State<CS>,
    ) -> Vec<EzEvent<CID, CM>> {
        match self.ships.get_mut(id) {
            None => {
                warn!("Forwarding to missing ship {:?}", id);
                vec![]
            }
            Some(port) => port.on_event(event, state),
        }
    }
    pub(crate) fn init_ships(&mut self, state: &mut State<CS>) -> Vec<EzEvent<CID, CM>> {
        self.ships
            .iter_mut()
            .flat_map(|(_, s)| s.init(state))
            .collect()
    }

    /// Forward the tick calls to all ships
    pub(crate) fn tick(&mut self, state: &mut State<CS>) -> Vec<EzEvent<CID, CM>> {
        self.ships
            .iter_mut()
            .flat_map(|(_, ship)| ship.tick(state))
            .collect()
    }

    pub(crate) fn register_internal(
        &mut self,
        ez_id: EzShipId<SID>,
        ship: BoxedShip<CID, CA, CS, CM>,
    ) -> Result<()> {
        if self.registered_internal(&ez_id) {
            Err(PortError::ShipAlreadyRegistered.into())
        } else {
            self.ships.insert(ez_id, ship);
            Ok(())
        }
    }

    pub(crate) fn unregister_internal(&mut self, ez_id: &EzShipId<SID>) -> Result<()> {
        if !self.registered_internal(ez_id) {
            return Err(PortError::ShipNotFound.into());
        }
        self.ships.remove(ez_id);
        Ok(())
    }

    pub(crate) fn registered_internal(&self, ez_id: &EzShipId<SID>) -> bool {
        self.ships.contains_key(ez_id)
    }
}

impl From<PortError> for Error {
    fn from(value: PortError) -> Self {
        Error::Port(value)
    }
}