repository!: rename easy::reference::log::State to easy::reference::Logs (#164)

Author: Byron

git-repository/CHANGELOG.md

@@ -3,6 +3,7 @@
 - Change return value of `prelude::RepositoryAccessExt::committer()` from `git_actor::Signature` to `Result<git_actor::Signature, easy::borrow:repo::Error>`
 - Change return value of `prelude::ReferenceAccessExt` from `Result<Vec<RefEdit>>, _>` to `Result<easy::Reference, _>`.
 - Rename `State` structs that serve as platform for iterators or other dependent types into `Platform`. These are usually intermediate objects only.
+- Rename `easy::Reference::log()` into `easy::Reference::logs()`
 
 ### v0.9.1 (2021-09-10)
 

git-repository/src/easy/ext/reference.rs

@@ -207,7 +207,7 @@ pub trait ReferenceAccessExt: easy::Access + Sized {
 
     /// Return a platform for iterating references.
     ///
-    /// Common kinds of iteration are [all][easy::reference::iter::State::all()] or [prefixed][easy::reference::iter::State::prefixed()]
+    /// Common kinds of iteration are [all][easy::reference::iter::Platform::all()] or [prefixed][easy::reference::iter::Platform::prefixed()]
     /// references.
     fn references(&self) -> Result<easy::reference::iter::Platform<'_, Self>, easy::reference::iter::Error> {
         let state = self.state();

git-repository/src/easy/head.rs

@@ -69,7 +69,7 @@ pub mod log {
         easy::{ext::ReferenceAccessExt, Head},
     };
 
-    /// The error returned by [Head::log()].
+    /// The error returned by [Head::logs()].
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {
@@ -84,8 +84,8 @@ pub mod log {
         A: easy::Access + Sized,
     {
         /// Return a platform for obtaining iterators on the reference log associated with the `HEAD` reference.
-        pub fn log(&self) -> Result<easy::reference::log::Platform<'repo, A, easy::Reference<'repo, A>>, Error> {
-            Ok(easy::reference::log::Platform {
+        pub fn logs(&self) -> Result<easy::reference::Logs<'repo, A, easy::Reference<'repo, A>>, Error> {
+            Ok(easy::reference::Logs {
                 reference: self.access.find_reference("HEAD")?,
                 buf: self.access.state().try_borrow_mut_buf()?,
                 _phantom: PhantomData::default(),

git-repository/src/easy/oid.rs

@@ -96,15 +96,6 @@ pub mod ancestors {
         }
     }
 
-    /// The iterator returned by [`Ancestors::all()`].
-    pub struct Iter<'a, 'repo, A>
-    where
-        A: easy::Access + Sized,
-    {
-        access: &'repo A,
-        inner: Box<dyn Iterator<Item = Result<git_hash::ObjectId, git_traverse::commit::ancestors::Error>> + 'a>,
-    }
-
     impl<'repo, A> Ancestors<'repo, A>
     where
         A: easy::Access + Sized,
@@ -130,6 +121,15 @@ pub mod ancestors {
         }
     }
 
+    /// The iterator returned by [`Ancestors::all()`].
+    pub struct Iter<'a, 'repo, A>
+    where
+        A: easy::Access + Sized,
+    {
+        access: &'repo A,
+        inner: Box<dyn Iterator<Item = Result<git_hash::ObjectId, git_traverse::commit::ancestors::Error>> + 'a>,
+    }
+
     impl<'a, 'repo, A> Iterator for Iter<'a, 'repo, A>
     where
         A: easy::Access + Sized,

git-repository/src/easy/reference/iter.rs

@@ -64,7 +64,7 @@ where
 
 ///
 pub mod init {
-    /// The error returned by [`State::all()`][super::State::all()] or [`State::prefixed()`][super::State::prefixed()].
+    /// The error returned by [`Platform::all()`][super::Platform::all()] or [`Platform::prefixed()`][super::Platform::prefixed()].
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {

git-repository/src/easy/reference/log.rs renamed to git-repository/src/easy/reference/logs.rs

@@ -1,26 +1,18 @@
 //!
-use std::{borrow::Borrow, cell::RefMut, marker::PhantomData, ops::DerefMut};
+use std::{borrow::Borrow, ops::DerefMut};
 
 use git_ref::file::ReferenceExt;
 
-use crate::{easy, easy::Reference};
-
-/// A platform to obtain iterators over reference logs.
-#[must_use = "Iterators should be obtained from this log platform"]
-pub struct Platform<'repo, A: 'repo, R>
-where
-    R: Borrow<Reference<'repo, A>>,
-{
-    pub(crate) reference: R,
-    pub(crate) buf: RefMut<'repo, Vec<u8>>,
-    pub(crate) _phantom: PhantomData<A>,
-}
+use crate::{
+    easy,
+    easy::{reference::Logs, Reference},
+};
 
 ///
 pub mod init {
     use crate::easy;
 
-    /// The error returned by [State::iter()][super::State::iter()] and [State::iter_rev()][super::State::iter_rev()].
+    /// The error returned by [Logs::iter()][super::Logs::iter()] and [Logs::iter_rev()][super::Logs::iter_rev()].
     #[derive(Debug, thiserror::Error)]
     #[allow(missing_docs)]
     pub enum Error {
@@ -37,7 +29,7 @@ pub type ReverseIter<'a> = git_ref::file::log::iter::Reverse<'a, std::fs::File>;
 /// An iterator over reference logs, oldest to newest.
 pub type ForwardIter<'a> = git_ref::file::log::iter::Forward<'a>;
 
-impl<'repo, A, R> Platform<'repo, A, R>
+impl<'repo, A, R> Logs<'repo, A, R>
 where
     A: easy::Access + Sized,
     R: Borrow<Reference<'repo, A>>,
@@ -59,7 +51,7 @@ where
     /// Return an iterator over reference logs, from oldest to newest.
     ///
     /// The iterator is optimized for rewriting the processing or rewriting the entire log.
-    /// For accessing only the most recent entries, see [`iter_rev()`][State::iter_rev()].
+    /// For accessing only the most recent entries, see [`iter_rev()`][Logs::iter_rev()].
     pub fn iter(&mut self) -> Result<Option<ForwardIter<'_>>, init::Error> {
         let buf = self.buf.deref_mut();
         Ok(self
@@ -75,8 +67,8 @@ where
     A: easy::Access + Sized,
 {
     /// Return a platform for obtaining iterators over reference logs.
-    pub fn log(&self) -> Result<Platform<'repo, A, &'_ Reference<'repo, A>>, easy::borrow::state::Error> {
-        Ok(Platform {
+    pub fn logs(&self) -> Result<Logs<'repo, A, &'_ Reference<'repo, A>>, easy::borrow::state::Error> {
+        Ok(Logs {
             reference: self,
             buf: self.access.state().try_borrow_mut_buf()?,
             _phantom: Default::default(),

git-repository/src/easy/reference/mod.rs

@@ -12,9 +12,11 @@ use crate::{
 pub mod iter;
 
 mod errors;
+use std::{borrow::Borrow, cell::RefMut, marker::PhantomData};
+
 pub use errors::{edit, find, namespace, peel};
 
-pub mod log;
+pub mod logs;
 pub(crate) mod packed;
 
 /// Access
@@ -35,6 +37,17 @@ impl<'repo, A> Reference<'repo, A> {
     }
 }
 
+/// A platform to obtain iterators over reference logs.
+#[must_use = "Iterators should be obtained from this log platform"]
+pub struct Logs<'repo, A: 'repo, R>
+where
+    R: Borrow<Reference<'repo, A>>,
+{
+    pub(crate) reference: R,
+    pub(crate) buf: RefMut<'repo, Vec<u8>>,
+    pub(crate) _phantom: PhantomData<A>,
+}
+
 impl<'repo, A> Reference<'repo, A>
 where
     A: easy::Access + Sized,

git-repository/src/lib.rs

@@ -47,7 +47,7 @@
 //!   However, other ways to adjust the `Repository` of long-running applications are possible. For instance, there could be a flag that
 //!   indicates a new `Repository` should be created (for instance, after it was changed) which causes the next server connection to
 //!   create a new one. This instance is the one to use when spawning new `EasyArc` instances.
-//! * `Platform` types are used to hold mutable or shared versions of required state for use in dependent objects they create, like iterators.
+//! * 'Platform' types are used to hold mutable or shared versions of required state for use in dependent objects they create, like iterators.
 //!   These come with the benefit of allowing for nicely readable call chains.
 //!
 //! ### Terminology

git-repository/tests/easy/ext/object.rs

@@ -61,7 +61,7 @@ mod commit {
         let head = repo.head()?.into_referent();
         assert_eq!(head.name().as_bstr(), "refs/heads/main", "'main' is the default name");
         assert_eq!(
-            head.log()?
+            head.logs()?
                 .iter_rev()?
                 .expect("log present")
                 .next()
@@ -94,7 +94,7 @@ mod commit {
 
         let head_log_entries: Vec<_> = repo
             .head()?
-            .log()?
+            .logs()?
             .iter_rev()?
             .expect("log present")
             .map(Result::unwrap)
@@ -127,7 +127,7 @@ mod commit {
         let current_commit = branch.peel_to_id_in_place()?;
         assert_eq!(current_commit, second_commit_id, "the commit was set");
 
-        let mut log = branch.log()?;
+        let mut log = branch.logs()?;
         let mut log_iter = log.iter_rev()?.expect("log present");
         assert_eq!(
             log_iter.next().expect("one line")?.message,