Prepare design of data

1 files changed, 93 insertions, 0 deletions

diff --git a/src/data.rs b/src/data.rs
new file mode 100644
index 0000000..3910dda
--- /dev/null
+++ b/src/data.rs
@@ -0,0 +1,93 @@
+// 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;
+}