using System.Collections.Generic;

namespace Chernobyl.Collections.Generic.Hierarchy
{
    /// <summary>
    /// An <see cref="IEnumerable{T}"/> type for types that are structured 
    /// like the node on a tree where the type holds a list of it's own type. 
    /// For example:
    /// <code>
    /// class Foobar
    /// {
    ///     public List{Foobar} Children { get; }
    /// }
    /// </code>
    /// This interface also derives from <see cref="IEnumerable{T}"/> whose 
    /// <see cref="IEnumerable{T}.GetEnumerator()"/> methods should return the  
    /// iterator best suited for that particular tree whether for speed or 
    /// practicality.
    /// 
    /// Note to implementors: Chernobyl offers two classes that can help with 
    /// the implementation of an <see cref="ITreeEnumerable{T}"/>. The 
    /// <see cref="IEnumerator{T}"/>s <see cref="DepthFirstEnumerator{T}"/> and 
    /// <see cref="BreadthFirstEnumerator{T}"/> allow for iteration over a tree 
    /// composed of types structured like tree nodes in depth and breadth first 
    /// order, respectively. Also, the <see cref="EnumeratorFactory{T}"/> can 
    /// be used to with the previously mentioned <see cref="IEnumerator{T}"/>s.
    /// To add to our Foobar example above, you would extend that class like so:
    /// <code>
    /// class Foobar : ITreeEnumerable{Foobar}
    /// {
    ///     public List{Foobar} Children { get; }
    ///     
    ///     public IEnumerable{Foobar} DepthFirst
    ///     {
    ///         get { return new EnumeratorFactory{Foobar}(() => new DepthFirstEnumerator{Foobar}(this, item => item.Children.GetEnumerator())); }
    ///     }
    ///
    ///     public IEnumerable{Foobar} BreadthFirst
    ///     {
    ///         get { return new EnumeratorFactory{Foobar}(() => new BreadthFirstEnumerator{Foobar}(this, item => item.Children.GetEnumerator())); }
    ///     }
    ///     
    ///     public IEnumerator{T} GetEnumerator()
    ///     {
    ///         return DepthFirst.GetEnumerator();
    ///     }
    ///
    ///     IEnumerator IEnumerable.GetEnumerator()
    ///     {
    ///         return GetEnumerator();
    ///     }
    /// }
    /// </code>
    /// 
    /// </summary>
    /// <typeparam name="T">The type that is structured like the node of a tree.</typeparam>
    public interface ITreeEnumerable<T> : IEnumerable<T>
    {
        /// <summary>
        /// An <see cref="IEnumerable{T}"/> that iterates over an 
        /// <see cref="ITreeEnumerable{T}"/> in depth first order (see 
        /// http://en.wikipedia.org/wiki/Depth-first_search for more information).
        /// </summary>
        IEnumerable<T> DepthFirst { get; }

        /// <summary>
        /// An <see cref="IEnumerable{T}"/> that iterates over an 
        /// <see cref="ITreeEnumerable{T}"/> in breadth first order (see 
        /// http://en.wikipedia.org/wiki/Breadth-first_search for more information).
        /// </summary>
        IEnumerable<T> BreadthFirst { get; }
    }
}