BeatSaber-IPA-Reloaded/IPA.Loader/Config/Stores/ValueConverter.cs

#nullable enable
using IPA.Config.Data;
using System;

namespace IPA.Config.Stores
{
    /// <summary>
    /// The base interface for a value converter for use by objects generated by
    /// <see cref="GeneratedStore.Generated{T}(Config, bool)"/>.
    /// </summary>
    /// <remarks>
    /// <para>
    /// The object returned from <see cref="FromValue(Value, object)"/>, if fed into <see cref="ToValue(object, object)"/>,
    /// should return equivalent <see cref="Value"/> structures. Similarly, if the result of <see cref="ToValue(object, object)"/>
    /// is fed into <see cref="FromValue(Value, object)"/>, the resulting object should be equivalent to the one passed to 
    /// <see cref="ToValue(object, object)"/>.
    /// </para>
    /// <para>
    /// The <c>parent</c> parameter to <see cref="ToValue(object, object)"/> and <see cref="FromValue(Value, object)"/> should
    /// be (ideally) the the top of the serialization tree, or some other generated object in that tree, rather than some arbitrary
    /// object in the middle that is not managed by the generatd config system.
    /// </para>
    /// <para>
    /// Converters do <i>not</i> need to perform null checks, as the serializer and deserializer will do that automatically.
    /// </para>
    /// </remarks>
    public interface IValueConverter
    {
        /// <summary>
        /// Converts the given object to a <see cref="Value"/>.
        /// </summary>
        /// <param name="obj">the object to convert</param>
        /// <param name="parent">the owning object of <paramref name="obj"/></param>
        /// <returns>a representation of <paramref name="obj"/> as a <see cref="Value"/> structure</returns>
        Value? ToValue(object? obj, object parent);
        /// <summary>
        /// Converts the given <see cref="Value"/> to the object type handled by this converter.
        /// </summary>
        /// <param name="value">the <see cref="Value"/> to deserialize</param>
        /// <param name="parent">the object that will own the result</param>
        /// <returns>the deserialized object</returns>
        object? FromValue(Value? value, object parent);
        /// <summary>
        /// Gets the type that this <see cref="IValueConverter"/> handles.
        /// </summary>
        Type Type { get; }
    }

    /// <summary>
    /// A strongly-typed <see cref="IValueConverter"/>.
    /// </summary>
    /// <typeparam name="T">the type of object to handle</typeparam>
    /// <seealso cref="IValueConverter"/>
    public abstract class ValueConverter<T> : IValueConverter
    {
        /// <summary>
        /// Converts the given object to a <see cref="Value"/>.
        /// </summary>
        /// <param name="obj">the object to convert</param>
        /// <param name="parent">the owning object of <paramref name="obj"/></param>
        /// <returns>a representation of <paramref name="obj"/> as a <see cref="Value"/> structure</returns>
        /// <seealso cref="IValueConverter.ToValue"/>
        public abstract Value? ToValue(T? obj, object parent);
        /// <summary>
        /// Converts the given <see cref="Value"/> to the object type handled by this converter.
        /// </summary>
        /// <param name="value">the <see cref="Value"/> to deserialize</param>
        /// <param name="parent">the object that will own the result</param>
        /// <returns>the deserialized object</returns>
        /// <seealso cref="IValueConverter.FromValue"/>
        public abstract T? FromValue(Value? value, object parent);

        Value? IValueConverter.ToValue(object? obj, object parent) => ToValue((T?)obj, parent);
        object? IValueConverter.FromValue(Value? value, object parent) => FromValue(value, parent);
        Type IValueConverter.Type => typeof(T);
    }
}