// 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/>.

//! This module handles data source retrieval, parsing and processing.
//!
//! Data sources identify where to find repos and projects, among other things.

use std::error;
use std::hash::Hash;
use std::time::Duration;

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

/// A source of data.
pub trait DataSourceBase {
    /// Refreshes the data associated with this source, if necessary, and
    /// returns the interval at which this should be called again.
    ///
    /// # Errors
    ///
    /// Returns an error if the source could not be updated. If an error is
    /// returned, an attempt should be made to **not** invalidate this data
    /// source, but instead carry on using stale data. Note that an aggregate
    /// data source may partially update and return an aggregate error type.
    fn update(&mut self) -> (
        Duration,
        Result<(), Box<dyn error::Error + Send + Sync + 'static>>,
    );

    /// 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 [`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.
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;
}