using System.Collections.Generic;
using System.IO;

namespace Chernobyl
{
    /// <summary>
    /// An interface for working with types that are used to hold several 
    /// file/folder paths for so that other systems can search these paths for 
    /// files, folders, etc. Derived types will automatically convert all '\' to 
    /// '/' for cross platform purposes.
    /// </summary>
    public interface ISearchPaths : ICollection<string>
    {
        /// <summary>
        /// Searches the search paths for a file that matches the search pattern
        /// and returns a FileStream (for reading only) to that file or null if 
        /// no file could be found. Only the first file found is returned. This 
        /// method does not search subdirectories.
        /// </summary>
        /// <param name="searchPattern">The pattern to look for when searching
        /// for the file. See the search pattern parameter on 
        /// <see cref="Directory.GetFiles(string)"/> for more information on 
        /// this parameter</param>
        /// <param name="fileMode">Specifies how the file should be opened.</param>
        /// <returns>The FileStream to the found file or null if no file could
        /// be found.</returns>
        FileStream Find(string searchPattern, FileMode fileMode);

        /// <summary>
        /// Searches the search paths for a file that matches the search pattern
        /// and returns a FileStream (for reading only) to that file or null if 
        /// no file could be found.
        /// </summary>
        /// <param name="searchPattern">The pattern to look for when searching
        /// for the file. See the search pattern parameter on 
        /// <see cref="Directory.GetFiles(string)"/> for more information on 
        /// this parameter</param>
        /// <param name="searchOptions">Specifies how each of the search paths
        /// should be searched. See the searchOptions parameter on 
        /// <see cref="Directory.GetFiles(string)"/> for more information.</param>
        /// <param name="fileMode">Specifies how the file should be opened.</param>
        /// <returns>The FileStream to the found file or null if no file could
        /// be found.</returns>
        FileStream Find(string searchPattern, SearchOption searchOptions, FileMode fileMode);

        /// <summary>
        /// Searches the search paths for a file that matches the search pattern
        /// and returns a FileStream to that file or null if no file could be 
        /// found.
        /// </summary>
        /// <param name="searchPattern">The pattern to look for when searching
        /// for the file. See the search pattern parameter on 
        /// <see cref="Directory.GetFiles(string)"/> for more information on 
        /// this parameter</param>
        /// <param name="searchOptions">Specifies how each of the search paths
        /// should be searched. See the searchOptions parameter on 
        /// <see cref="Directory.GetFiles(string)"/> for more information.</param>
        /// <param name="fileMode">Specifies how the file should be opened.</param>
        /// <param name="fileAccess">Specifies what operations you want to do on
        /// the file.</param>
        /// <returns>The FileStream to the found file or null if no file could
        /// be found.</returns>
        FileStream Find(string searchPattern, SearchOption searchOptions, FileMode fileMode, FileAccess fileAccess);

        /// <summary>
        /// Returns the first path to the file specified.
        /// </summary>
        /// <param name="file">The name of the file to look for.</param>
        /// <returns>The path to the file specified.</returns>
        string FindFilePath(string file);

        /// <summary>
        /// Returns an enumerator of file paths that are contained
        /// in this SearchPath. Only paths to files that actually 
        /// exist are returned.
        /// </summary>
        /// <param name="filepathAppendage">A string that should be
        /// appended to the end of the contained file paths before they
        /// are searched for existence.</param>
        /// <returns>An enumerator of paths to files that exist.</returns>
        IEnumerable<string> FilePaths(string filepathAppendage);

        /// <summary>
        /// Returns an enumerator of file paths that are contained
        /// in this SearchPath. Only paths to files that actually 
        /// exist are returned.
        /// </summary>
        /// <returns>An enumerator of paths to files that exist.</returns>
        IEnumerable<string> FilePaths();

        /// <summary>
        /// Returns an enumerator of folder paths that are contained
        /// in this SearchPath. Only paths to folders that actually 
        /// exist are returned.
        /// </summary>
        /// <param name="directorypathAppendage">A string that should be
        /// appended to the end of the contained folder paths before they
        /// are searched for existence.</param>
        /// <returns>An enumerator of paths to folders that exist.</returns>
        IEnumerable<string> DirectoryPaths(string directorypathAppendage);

        /// <summary>
        /// Returns an enumerator of folder paths that are contained
        /// in this SearchPath. Only paths to folders that actually 
        /// exist are returned.
        /// </summary>
        /// <returns>An enumerator of paths to folders that exist.</returns>
        IEnumerable<string> DirectoryPaths();

        /// <summary>
        /// Returns an enumeration of FileStreams created
        /// from search paths in this class. Any FileStreams
        /// to files which do not exist will not be returned.
        /// </summary>
        /// <param name="filepathAppendage">A string that should be appended 
        /// to the front of each of the SearchPaths before they are checked for
        /// existence or created.</param>
        /// <param name="fileMode">The FileMode to open the files with.</param>
        /// <returns>An enumeration of FileStreams which point to the files
        /// pointed to by the search paths.</returns>
        IEnumerable<FileStream> Files(FileMode fileMode, string filepathAppendage);

        /// <summary>
        /// Returns an enumeration of FileStreams created
        /// from search paths in this class. Any FileStreams
        /// to files which do not exist will not be returned.
        /// </summary>
        /// <param name="fileMode">The FileMode to open the files with.</param>
        /// <returns>An enumeration of FileStreams which point to the files
        /// pointed to by the search paths.</returns>
        IEnumerable<FileStream> Files(FileMode fileMode);
    }
}