// This file is part of GAnarchy - decentralized development hub
// Copyright (C) 2021  Soni L.
// 
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public License as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
// 
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU Affero General Public License for more details.
// 
// You should have received a copy of the GNU Affero General Public License
// along with this program.  If not, see <https://www.gnu.org/licenses/>.

//! Data sources and their functionality.
//!
//! Data sources are the primary means by which GAnarchy figures out what
//! data to work with, and managers help combine and filter data sources into
//! producing the desired data for the operation of an instance.

use std::error;
use std::hash::Hash;

pub mod effective;
pub mod kinds;
pub mod managers;
pub mod sources;

#[cfg(test)]
mod tests;

/// A source of data.
pub trait DataSourceBase: std::fmt::Display {
    /// Refreshes the data associated with this source.
    fn update(&mut self) -> Update;

    /// Returns whether this data source contains any (valid) data.
    ///
    /// # Panics
    ///
    /// This is allowed (but not required) to panic if called before `update`,
    /// but should not panic if `update` has been called, but failed.
    fn exists(&self) -> bool;
}

/// A source of data of some specified kind.
pub trait DataSource<T: Kind>: DataSourceBase {
    /// Returns the values associated with this kind.
    ///
    /// # Panics
    ///
    /// This is allowed (but not required) to panic if called before `update`,
    /// but should not panic if `update` has been called, but failed.
    fn get_values(&self) -> T::Values;

    /// Returns the value associated with this kind.
    ///
    /// This is the same as [`DataSource::get_values`] but allows using the
    /// singular name, for kinds with up to only one value.
    ///
    /// # Panics
    ///
    /// This is allowed (but not required) to panic if called before `update`,
    /// but should not panic if `update` has been called, but failed.
    fn get_value(&self) -> Option<T> where T: Kind<Values=Option<T>> {
        self.get_values()
    }
}

/// A kind of value that can be retrieved from a data source.
pub trait Kind {
    /// Values of this kind.
    type Values: IntoIterator<Item=Self>;
}

/// A kind of value that can be retrieved from a data source, which can
/// override values of the same kind based on a key.
pub trait OverridableKind: Kind {
    /// The key, as in a map key, that gets overridden.
    type Key: Hash + Eq + Ord;

    /// Returns the key for use in a key-value map such as a `BTreeMap` or
    /// a set such as `BTreeSet`.
    fn as_key(&self) -> &Self::Key;
}

/// Stats about an update.
#[derive(Default)]
pub struct Update {
    /// Errors collected in an update.
    pub errors: Vec<Box<dyn error::Error + Send + Sync + 'static>>,
}