databoard 0.4.0

// Copyright © 2025 Stephan Kunz
//! A thread safe hierarchical name/value store.
#![allow(unused)]

#[cfg(feature = "std")]
extern crate std;

use core::str::FromStr;

use alloc::string::String;

use dataport::{
	AnyPortValue, BindCommons, BoundValueReadGuard, BoundValueWriteGuard, PortCollection, PortCollectionAccessors,
	PortCollectionAccessorsCommon, PortCollectionMut, PortCollectionProviderMut, PortList, PortMap, PortVariant,
};

use crate::{Arc, ConstString, Error, RemappingList, RemappingTarget, RwLock, check_local_key, check_top_level_key};

/// A hierarchical, thread safe name/value store.
/// The name is something that can be converted into an `Arc<str>`.
/// The value can be anything that implements the traits `Any` and `Debug`.
///
/// `Databoard` has internal mutability.
#[derive(Clone, Default)]
#[repr(transparent)]
pub struct Databoard(Arc<RwLock<DataboardInner>>);

/// Terminal arm of a key resolution — the operation must fail with this error.
enum ShortCircuit {
	/// The remapping is a string assignment, not a valid lookup target.
	Assignment { name: ConstString, value: ConstString },
	/// The remapping points to a parent that does not exist.
	NoParent { name: ConstString, remapped: ConstString },
}

impl From<ShortCircuit> for Error {
	fn from(sc: ShortCircuit) -> Self {
		match sc {
			ShortCircuit::Assignment { name, value } => Self::Assignment { name, value },
			ShortCircuit::NoParent { name, remapped } => Self::NoParent { name, remapped },
		}
	}
}

impl From<ShortCircuit> for dataport::Error {
	fn from(sc: ShortCircuit) -> Self {
		Error::from(sc).into()
	}
}

/// Describes how a read-only key-operation should be dispatched.
enum Resolve {
	/// Delegate to another databoard (root or parent) with the given name.
	Redirect(Databoard, ConstString),
	/// Resolve against the local database with the given name.
	Local(ConstString),
	/// The key resolves to a terminal error.
	ShortCircuit(ShortCircuit),
}

/// Describes how a write-mode key-operation should be dispatched.
///
/// The `Local` variant carries a held write guard, so the caller performs the
/// mutation inside the same lock scope used for the remapping lookup.
enum ResolveMut<'a> {
	/// Delegate to another databoard (root or parent) with the given name.
	Redirect(Databoard, ConstString),
	/// Resolve against the local database; the guard is already acquired.
	Local(ConstString, crate::RwLockWriteGuard<'a, DataboardInner>),
	/// The key resolves to a terminal error.
	ShortCircuit(ShortCircuit),
}

impl Databoard {
	pub fn insert(&mut self, name: ConstString, port: PortVariant) -> Result<(), dataport::Error> {
		match self.resolve_mut(&name, false) {
			ResolveMut::Redirect(mut board, resolved) => board.insert(resolved, port),
			ResolveMut::Local(resolved, mut guard) => guard.insert(resolved, port),
			ResolveMut::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	pub fn remove(&mut self, name: &str) -> Result<PortVariant, dataport::Error> {
		match self.resolve_mut(name, false) {
			ResolveMut::Redirect(mut board, resolved) => board.remove(&resolved),
			ResolveMut::Local(resolved, mut guard) => PortCollectionMut::delete(&mut guard.database, &resolved),
			ResolveMut::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	/// Creates a [`Databoard`] with given parameters.
	#[must_use]
	pub fn with(parent: Option<Self>, remappings: Option<RemappingList>, autoremap: bool) -> Self {
		Self(Arc::new(RwLock::new(DataboardInner {
			database: PortMap::default(),
			parent,
			remappings: remappings.unwrap_or_default(),
			autoremap,
		})))
	}

	/// Creates a [`Databoard`] using the given parent.
	/// The parents entries are automatically remapped into the new databoard.
	#[must_use]
	pub fn with_parent(parent: Self) -> Self {
		Self(Arc::new(RwLock::new(DataboardInner {
			database: PortMap::default(),
			parent: Some(parent),
			remappings: RemappingList::default(),
			autoremap: true,
		})))
	}
	/// Prints the content of the [`Databoard`] for debugging purpose.
	#[cfg(feature = "std")]
	pub fn debug_message(&self) {
		let _ = self.0.read().parent;
		std::println!("not yet implemented");
	}

	/// Returns a reference to the root [`Databoard`] of the hierarchy.
	fn root(&self) -> Self {
		let mut current = self.clone();
		loop {
			let next = current.0.read().parent.clone();
			match next {
				Some(parent) => current = parent,
				None => return current,
			}
		}
	}

	/// Resolves `name` into a [`Resolve`] directive describing how to dispatch the operation.
	///
	/// When `strict_root` is true, a `RootPointer` remapping without a parent yields
	/// [`ShortCircuit::NoParent`] instead of falling back to the local database — required by
	/// `give_to_bound` and `use_from_bound`.
	fn resolve(&self, name: &str, strict_root: bool) -> Resolve {
		if let Ok(stripped) = check_top_level_key(name) {
			return Resolve::Redirect(self.root(), stripped.into());
		}
		if let Ok(local) = check_local_key(name) {
			return Resolve::Local(local.into());
		}

		let (target, parent, autoremap) = {
			let guard = self.0.read();
			(guard.remappings.find(name), guard.parent.clone(), guard.autoremap)
		};

		match target {
			RemappingTarget::BoardPointer(remapped) => match parent {
				Some(p) => Resolve::Redirect(p, remapped),
				None => Resolve::ShortCircuit(ShortCircuit::NoParent {
					name: name.into(),
					remapped,
				}),
			},
			RemappingTarget::LocalPointer(remapped) => Resolve::Local(remapped),
			RemappingTarget::RootPointer(remapped) => {
				if parent.is_some() {
					Resolve::Redirect(self.root(), remapped)
				} else if strict_root {
					Resolve::ShortCircuit(ShortCircuit::NoParent {
						name: name.into(),
						remapped,
					})
				} else {
					Resolve::Local(remapped)
				}
			}
			RemappingTarget::StringAssignment(value) => Resolve::ShortCircuit(ShortCircuit::Assignment {
				name: name.into(),
				value,
			}),
			RemappingTarget::None(original) => {
				if autoremap && let Some(parent) = parent {
					Resolve::Redirect(parent, original)
				} else {
					Resolve::Local(original)
				}
			}
		}
	}

	/// Write-lock-holding variant of [`Self::resolve`].
	///
	/// Acquires a write lock for the remapping lookup and — when the operation resolves locally —
	/// hands the same guard back to the caller so the mutation runs inside one lock scope.
	/// For `Redirect` and `ShortCircuit` outcomes the guard is released before returning.
	fn resolve_mut(&self, name: &str, strict_root: bool) -> ResolveMut<'_> {
		if let Ok(stripped) = check_top_level_key(name) {
			return ResolveMut::Redirect(self.root(), stripped.into());
		}
		if let Ok(local) = check_local_key(name) {
			return ResolveMut::Local(local.into(), self.0.write());
		}

		let guard = self.0.write();
		let target = guard.remappings.find(name);
		match target {
			RemappingTarget::BoardPointer(remapped) => {
				let parent = guard.parent.clone();
				drop(guard);
				match parent {
					Some(p) => ResolveMut::Redirect(p, remapped),
					None => ResolveMut::ShortCircuit(ShortCircuit::NoParent {
						name: name.into(),
						remapped,
					}),
				}
			}
			RemappingTarget::LocalPointer(remapped) => ResolveMut::Local(remapped, guard),
			RemappingTarget::RootPointer(remapped) => {
				if guard.parent.is_some() {
					drop(guard);
					ResolveMut::Redirect(self.root(), remapped)
				} else if strict_root {
					ResolveMut::ShortCircuit(ShortCircuit::NoParent {
						name: name.into(),
						remapped,
					})
				} else {
					ResolveMut::Local(remapped, guard)
				}
			}
			RemappingTarget::StringAssignment(value) => ResolveMut::ShortCircuit(ShortCircuit::Assignment {
				name: name.into(),
				value,
			}),
			RemappingTarget::None(original) => {
				if guard.autoremap
					&& let Some(parent) = guard.parent.clone()
				{
					drop(guard);
					ResolveMut::Redirect(parent, original)
				} else {
					ResolveMut::Local(original, guard)
				}
			}
		}
	}

	/// Add a list of remappings to the databoard.
	/// # Errors
	/// - [`Error::AlreadyRemapped`] if a name is already remapped.
	pub fn add_remappings(&mut self, remappings: RemappingList) -> Result<(), Error> {
		let mut guard = self.0.write();
		let list = &mut *guard;
		let mut remappings = remappings.into_inner();
		while let Some(entry) = remappings.pop() {
			list.remappings.add_target(entry)?;
		}
		Ok(())
	}

	/// Returns a clone of the remappings, if there are any, otherwise `None`.
	#[must_use]
	pub fn remappings(&self) -> RemappingList {
		self.0.read().remappings.clone()
	}

	/// Returns a clone of the [`PortVariant`] stored under `name`.
	/// # Errors
	/// - [`Error::Assignment`] if the remapping contains an assignment of a `str` value.
	/// - [`Error::NoParent`]   if `name` is remapped to a parent without having a parent.
	/// - [`Error::NotFound`]   if `name` is not contained.
	pub fn entry(&self, name: &str) -> Result<PortVariant, Error> {
		match self.resolve(name, false) {
			Resolve::Redirect(board, resolved) => board.entry(&resolved),
			Resolve::Local(resolved) => self
				.0
				.read()
				.database
				.find(&resolved)
				.map_or_else(|| Err(Error::NotFound { name: name.into() }), |p| Ok(p.clone())),
			Resolve::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	/// Returns either a clone/copy of the T or if content is .
	/// Therefore T must implement [`Clone`] and [`FromStr`].
	/// # Errors
	/// - [`Error::ConversionFromStr`], if content of 'name' cannot be converted from `str` to T
	/// - [`Error::DataType`], if 'name' has not the expected type of T
	/// - [`Error::NotFound`], if 'name' is not in port collection.
	/// - [`Error::NoValue`], if 'name' has no value set.
	pub fn get_from_str<T: AnyPortValue + FromStr + Clone>(&self, key: &str) -> Result<T, Error> {
		match self.get(key) {
			Ok(res) => Ok(res),
			Err(err) => match err {
				dataport::Error::ReturnTypeMismatch { port, value } => {
					// try to convert from str
					T::from_str(&value).map_or_else(|_| Err(Error::ConversionFromStr { value, port }), |val| Ok(val))
				}
				dataport::Error::NotFound { name } => Err(Error::NotFound { name }),
				dataport::Error::NoValueSet => Err(Error::NoValue { name: key.into() }),
				// this is unreachable
				// dataport::Error::IsLocked => Err(Error::IsLocked { name: key.into() }),
				dataport::Error::DataType => Err(Error::DataType { name: key.into() }),
				// this shoul never be reached
				_ => Err(Error::Unreachable("get_from_str".into(), line!())),
			},
		}
	}

	/// Sets the port 'key' with a value parsed from the string `s`.
	///
	/// The port must have been created with a `_parseable` constructor
	/// (e.g. [`Self::create_outbound_parseable`]) so that the `FromStr`
	/// capability was captured at creation time.
	/// # Errors
	/// - [`Error::FromStr`], if parsing or the setter was not registered.
	/// - [`Error::PortType`], if the port variant does not support writing.
	pub fn set_from_str(&mut self, name: &str, value: &str) -> Result<(), dataport::Error> {
		match self.resolve_mut(name, false) {
			ResolveMut::Redirect(mut board, resolved) => board.set_from_str(&resolved, value),
			ResolveMut::Local(resolved, mut guard) => {
				if guard.database.contains_name(&resolved) {
					guard.database.set_from_str(&resolved, value)
				} else {
					guard
						.database
						.add(resolved, PortVariant::create_inoutbound(String::from(value)))
				}
			}
			ResolveMut::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	/// Sets the autoremapping flag to the desired value.
	pub fn set_autoremap(&mut self, autoremap: bool) {
		self.0.write().autoremap = autoremap;
	}

	/// Create a port using the corresponding port from the [`PortList`].
	/// # Errors
	pub fn create_from_collection(
		&mut self,
		name: ConstString,
		portlist: &dyn PortList,
		portlist_name: &str,
	) -> Result<(), dataport::Error> {
		portlist.find(portlist_name).map_or_else(
			|| {
				Err(dataport::Error::NotFound {
					name: portlist_name.into(),
				})
			},
			|variant| self.insert(name, variant.clone()),
		)
	}

	/// Create a port using the corresponding port from the [`PortList`].
	/// # Errors
	pub fn create_from_variant(&mut self, name: ConstString, variant: &PortVariant) -> Result<(), dataport::Error> {
		self.insert(name, variant.clone())
	}

	/// Adds a remapping to the blackboard.
	/// # Errors
	/// - [`Error::CreateRemapping`] if creation of the [`RemappingTarget`](crate::RemappingTarget) is not possible
	#[allow(clippy::option_if_let_else)]
	pub fn add_remapping(&mut self, key: &str, target: &str) -> Result<(), Error> {
		// handle target '{=}'
		let target = target.replace('=', key);
		let new_target = RemappingTarget::from_str(&target)?;
		let old_target = self.0.read().remappings.find(key);
		match old_target {
			RemappingTarget::None(_) => self
				.0
				.write()
				.remappings
				.add_target((key.into(), new_target)),
			_ => {
				if old_target == new_target {
					Err(Error::AlreadyExists { name: key.into() })
				} else {
					Err(Error::AlreadyRemapped {
						name: key.into(),
						remapped: target.into(),
					})
				}
			}
		}
	}

	/// Reverse search
	#[must_use]
	pub fn find_origin(&self, name: &str) -> Option<Arc<str>> {
		self.remappings().find_origin(name)
	}

	/// Provides shared access to the local [`PortCollection`] within a closure.
	///
	/// Since the underlying storage is behind an [`RwLock`](crate::RwLock),
	/// a direct `&dyn PortCollection` cannot be returned.
	/// This method acquires a read lock and passes the inner [`PortMap`] to the closure.
	pub fn with_collection<F, R>(&self, f: F) -> R
	where
		F: FnOnce(&PortMap) -> R,
	{
		let guard = self.0.read();
		f(&guard.database)
	}

	/// Provides exclusive access to the local [`PortCollection`] within a closure.
	///
	/// Since the underlying storage is behind an [`RwLock`](crate::RwLock),
	/// a direct `&mut dyn PortCollection` cannot be returned.
	/// This method acquires a write lock and passes the inner [`PortMap`] to the closure.
	pub fn with_collection_mut<F, R>(&self, f: F) -> R
	where
		F: FnOnce(&mut PortMap) -> R,
	{
		let mut guard = self.0.write();
		f(&mut guard.database)
	}
}

impl core::fmt::Debug for Databoard {
	fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
		let inner = self.0.read();
		write!(f, "Databoard {{ ")?;
		write!(f, "autoremap: {:?}", &inner.autoremap)?;
		write!(f, ", {:?}", &inner.database)?;
		write!(f, ", {:?}", &inner.remappings)?;
		write!(f, ", parent: ")?;
		if let Some(parent) = &inner.parent {
			write!(f, "{parent:?}",)
		} else {
			write!(f, "None")
		}?;
		write!(f, " }}")
	}
}

impl PortCollectionAccessorsCommon for Databoard {
	fn contains_name(&self, key: &str) -> bool {
		match self.resolve(key, false) {
			Resolve::Redirect(board, resolved) => board.contains_name(&resolved),
			Resolve::Local(resolved) => self.0.read().database.contains_name(&resolved),
			Resolve::ShortCircuit(_) => false,
		}
	}

	fn give_to_bound(&self, name: &str, bound: &mut dyn BindCommons) -> Result<(), dataport::Error> {
		match self.resolve_mut(name, true) {
			ResolveMut::Redirect(board, resolved) => board.give_to_bound(&resolved, bound),
			ResolveMut::Local(resolved, guard) => guard.database.give_to_bound(&resolved, bound),
			ResolveMut::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	fn give_to_collection(
		&self,
		name: &str,
		other_collection: &mut dyn PortCollection,
		other_name: &str,
	) -> Result<(), dataport::Error> {
		other_collection.find_mut(other_name).map_or_else(
			|| Err(dataport::Error::OtherNotFound { name: other_name.into() }),
			|other| self.give_to_variant(name, other),
		)
	}

	fn give_to_variant(&self, name: &str, variant: &mut PortVariant) -> Result<(), dataport::Error> {
		match variant {
			PortVariant::InBound(bound) => self.give_to_bound(name, bound),
			PortVariant::InOutBound(bound) => self.give_to_bound(name, bound),
			PortVariant::OutBound(bound) => self.give_to_bound(name, bound),
		}
	}

	fn sequence_number(&self, name: &str) -> Result<u32, dataport::Error> {
		match self.resolve(name, false) {
			Resolve::Redirect(board, resolved) => board.sequence_number(&resolved),
			Resolve::Local(resolved) => self.0.read().database.sequence_number(&resolved),
			Resolve::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	fn use_from_bound(&mut self, name: &str, bound: &dyn BindCommons) -> Result<(), dataport::Error> {
		match self.resolve_mut(name, true) {
			ResolveMut::Redirect(mut board, resolved) => board.use_from_bound(&resolved, bound),
			ResolveMut::Local(resolved, mut guard) => guard.database.use_from_bound(&resolved, bound),
			ResolveMut::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	fn use_from_collection(
		&mut self,
		name: &str,
		other_collection: &dyn PortCollection,
		other_name: &str,
	) -> Result<(), dataport::Error> {
		other_collection.find(other_name).map_or_else(
			|| Err(dataport::Error::OtherNotFound { name: other_name.into() }),
			|other| self.use_from_variant(name, other),
		)
	}

	fn use_from_variant(&mut self, name: &str, variant: &PortVariant) -> Result<(), dataport::Error> {
		match variant {
			PortVariant::InBound(bound) => self.use_from_bound(name, bound),
			PortVariant::InOutBound(bound) => self.use_from_bound(name, bound),
			PortVariant::OutBound(bound) => self.use_from_bound(name, bound),
		}
	}
}

impl PortCollectionAccessors for Databoard {
	fn contains<T: AnyPortValue>(&self, key: &str) -> Result<bool, dataport::Error> {
		match self.resolve(key, false) {
			Resolve::Redirect(board, resolved) => board.contains::<T>(&resolved),
			Resolve::Local(resolved) => self.0.read().database.contains::<T>(&resolved),
			Resolve::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	fn get<T: AnyPortValue + Clone>(&self, key: &str) -> Result<T, dataport::Error> {
		match self.resolve(key, false) {
			Resolve::Redirect(board, resolved) => board.get::<T>(&resolved),
			Resolve::Local(resolved) => self.0.read().database.get::<T>(&resolved),
			Resolve::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	fn read<T: AnyPortValue>(&self, key: &str) -> Result<BoundValueReadGuard<T>, dataport::Error> {
		match self.resolve(key, false) {
			Resolve::Redirect(board, resolved) => board.read(&resolved),
			Resolve::Local(resolved) => self.0.read().database.read(&resolved),
			Resolve::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	fn try_read<T: AnyPortValue>(&self, key: &str) -> Result<BoundValueReadGuard<T>, dataport::Error> {
		match self.resolve(key, false) {
			Resolve::Redirect(board, resolved) => board.try_read(&resolved),
			Resolve::Local(resolved) => self.0.read().database.try_read(&resolved),
			Resolve::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	fn replace<T: AnyPortValue>(&mut self, name: &str, value: T) -> Result<Option<T>, dataport::Error> {
		match self.resolve_mut(name, false) {
			ResolveMut::Redirect(mut board, resolved) => board.replace::<T>(&resolved, value),
			ResolveMut::Local(resolved, mut guard) => guard.database.replace::<T>(&resolved, value),
			ResolveMut::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	fn take<T: AnyPortValue>(&mut self, name: &str) -> Result<Option<T>, dataport::Error> {
		match self.resolve_mut(name, false) {
			ResolveMut::Redirect(mut board, resolved) => board.take::<T>(&resolved),
			ResolveMut::Local(resolved, mut guard) => PortCollectionAccessors::take::<T>(&mut guard.database, &resolved),
			ResolveMut::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	fn set<T: AnyPortValue>(&mut self, name: &str, value: T) -> Result<(), dataport::Error> {
		match self.resolve_mut(name, false) {
			ResolveMut::Redirect(mut board, resolved) => board.set::<T>(&resolved, value),
			ResolveMut::Local(resolved, mut guard) => {
				if guard.database.contains_name(&resolved) {
					guard.database.set::<T>(&resolved, value)
				} else {
					guard
						.database
						.add(resolved, PortVariant::create_inoutbound(value))
				}
			}
			ResolveMut::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	fn write<T: AnyPortValue>(&mut self, name: &str) -> Result<BoundValueWriteGuard<T>, dataport::Error> {
		match self.resolve_mut(name, false) {
			ResolveMut::Redirect(mut board, resolved) => board.write::<T>(&resolved),
			ResolveMut::Local(resolved, mut guard) => guard.database.write(&resolved),
			ResolveMut::ShortCircuit(sc) => Err(sc.into()),
		}
	}

	fn try_write<T: AnyPortValue>(&mut self, name: &str) -> Result<BoundValueWriteGuard<T>, dataport::Error> {
		match self.resolve_mut(name, false) {
			ResolveMut::Redirect(mut board, resolved) => board.try_write::<T>(&resolved),
			ResolveMut::Local(resolved, mut guard) => guard.database.try_write(&resolved),
			ResolveMut::ShortCircuit(sc) => Err(sc.into()),
		}
	}
}

/// Internal data for a hierarchical databoard.
#[derive(Default)]
struct DataboardInner {
	/// Database of this `Databoard`.
	/// It is behind an `RwLock` to protect against data races.
	database: PortMap,
	/// An optional reference to a parent `Databoard`.
	parent: Option<Databoard>,
	/// Manual remapping rules from this `Databoard` to the parent.
	remappings: RemappingList,
	/// Whether to use automatic remapping to parents content.
	autoremap: bool,
}

impl DataboardInner {
	fn insert(&mut self, name: ConstString, port: PortVariant) -> Result<(), dataport::Error> {
		// insertion into databoard always needs read- and writeable ports
		// so we need to convert all other ports
		let io_port = port.to_in_out();
		// self.database.insert(name, io_port)
		PortMap::add(&mut self.database, name, io_port)
	}
}

#[cfg(test)]
mod tests {
	use super::*;

	// check, that the auto traits are available
	const fn is_normal<T: Sized + Send + Sync>() {}

	#[test]
	const fn normal_types() {
		is_normal::<&DataboardInner>();
		is_normal::<DataboardInner>();
		is_normal::<&Databoard>();
		is_normal::<Databoard>();
	}

	// Read-only `resolve` with `strict_root = true` has no public caller.
	#[test]
	fn resolve_root_pointer_strict_no_parent() {
		let mut remappings = RemappingList::default();
		remappings.push(("alias".into(), RemappingTarget::RootPointer("rkey".into())));
		let db = Databoard::with(None, Some(remappings), false);

		// strict_root=true  → ShortCircuit::NoParent  (the path under test)
		// strict_root=false → Resolve::Local          (else-arm, covers the if-let's else branch)
		// Iterating both results through a single `if let` means both arms execute,
		// eliminating the zero-count sub-region that `assert!(matches!(…))` would leave.
		let results = [
			db.resolve("alias", true),
			db.resolve("alias", false),
		];
		let mut got_no_parent = false;
		for result in results {
			if let Resolve::ShortCircuit(ShortCircuit::NoParent { .. }) = result {
				got_no_parent = true;
			}
		}
		assert!(got_no_parent);
	}
}