/*
 * IReadable.cs
 * 
 * Copyright © 2009
 * Diversified Technical Systems, Inc.
 * All Rights Reserved
 */

namespace DTS.Serialization
{   ///
    /// <summary>
    /// Defines "readability" for DTS.Serialization objects.
    /// </summary>
    /// 
    public interface IReadable
    {   //
        // It's not that it doesn't take much to be readable, just that all non-trivial readable
        // definitions involve a specific type of object that the file is to be deserialized
        // into (see non-trivial IReadable interface below).  But one may want to reflect against
        // a general "IReadable" type for various reasons, i.e., to check to see if file-type object
        // is readable in general before presenting the user with read options on the UI (that will
        // perform polymorphic read functions on the object, natch).
    }   //

    /// <summary>
    /// Defines "readability" for DTS.Serialization objects.
    /// </summary>
    /// 
    /// <typeparam name="T">
    /// The type of object to be deserialized to.
    /// </typeparam>
    /// 
    public interface IReadable<T> : IReadable
    {   ///
        /// <summary>
        /// Get a deserializer to "read" an instance of this file format into the specified object type.
        /// </summary>
        /// 
        IReader<T> Importer { get; }
    }

    /// <summary>
    /// Defines the general requirements of a DTS.Serialization file reader object.
    /// </summary>
    public interface IReader
    {   //
        // It's not that it doesn't take much to be a reader, just that all non-trivial reader
        // definitions involve a specific type of object that the file is to be deserialized
        // into (see non-trivial IReader interface below).  But one may want to reflect against
        // a general "IReader" type for various reasons, i.e., to check to see if file-type object
        // is readable in general before presenting the user with read options on the UI (that will
        // perform polymorphic read functions on the object, natch).
    }   //

    /// <summary>
    /// Defines the non-trivial requirements of a DTS.Serialization file reader object.
    /// </summary>
    /// 
    /// <typeparam name="T">
    /// The type of object the file is to be deserialized into.
    /// </typeparam>
    /// 
    public interface IReader<T> : IReader
    {   ///
        /// <summary>
        /// Deserialize the path-specified serialization into the given object reference.
        /// </summary>
        /// 
        /// <param name="pathname">
        /// The <see cref="string"/> pathname at which the serialization can be found.
        /// </param>
        /// 
        /// <param name="target">
        /// The object to be initialized by the specified serialization.
        /// </param>
        /// 
        void Read(string pathname, out T target);
    }
}