From 625c538f244519700f3942b2b2969845db9a99b0 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <github@jplamondonw.com>
Date: Tue, 5 Jun 2018 20:22:46 -0400
Subject: move manifest parsing into toolkit (#532)

---
 .../Converters/ManifestContentPackForConverter.cs  |  50 +++++++++
 .../Converters/ManifestDependencyArrayConverter.cs |  60 ++++++++++
 .../Converters/SemanticVersionConverter.cs         |  36 ++++++
 .../Converters/SimpleReadOnlyConverter.cs          |  76 +++++++++++++
 .../Converters/StringEnumConverter.cs              |  22 ++++
 .../Serialisation/InternalExtensions.cs            |  21 ++++
 .../Serialisation/JsonHelper.cs                    | 123 +++++++++++++++++++++
 .../Serialisation/Models/LegacyManifestVersion.cs  |  26 +++++
 .../Serialisation/Models/Manifest.cs               |  49 ++++++++
 .../Serialisation/Models/ManifestContentPackFor.cs |  15 +++
 .../Serialisation/Models/ManifestDependency.cs     |  35 ++++++
 .../Serialisation/SParseException.cs               |  17 +++
 12 files changed, 530 insertions(+)
 create mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/Converters/ManifestContentPackForConverter.cs
 create mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/Converters/ManifestDependencyArrayConverter.cs
 create mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
 create mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/Converters/SimpleReadOnlyConverter.cs
 create mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/Converters/StringEnumConverter.cs
 create mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/InternalExtensions.cs
 create mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/JsonHelper.cs
 create mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/Models/LegacyManifestVersion.cs
 create mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs
 create mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestContentPackFor.cs
 create mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestDependency.cs
 create mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/SParseException.cs

(limited to 'src/StardewModdingAPI.Toolkit/Serialisation')

diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/ManifestContentPackForConverter.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/ManifestContentPackForConverter.cs
new file mode 100644
index 00000000..232c22a7
--- /dev/null
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/ManifestContentPackForConverter.cs
@@ -0,0 +1,50 @@
+using System;
+using Newtonsoft.Json;
+using StardewModdingAPI.Toolkit.Serialisation.Models;
+
+namespace StardewModdingAPI.Toolkit.Serialisation.Converters
+{
+    /// <summary>Handles deserialisation of <see cref="ManifestContentPackFor"/> arrays.</summary>
+    public class ManifestContentPackForConverter : JsonConverter
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>Whether this converter can write JSON.</summary>
+        public override bool CanWrite => false;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Get whether this instance can convert the specified object type.</summary>
+        /// <param name="objectType">The object type.</param>
+        public override bool CanConvert(Type objectType)
+        {
+            return objectType == typeof(ManifestContentPackFor[]);
+        }
+
+
+        /*********
+        ** Protected methods
+        *********/
+        /// <summary>Read the JSON representation of the object.</summary>
+        /// <param name="reader">The JSON reader.</param>
+        /// <param name="objectType">The object type.</param>
+        /// <param name="existingValue">The object being read.</param>
+        /// <param name="serializer">The calling serializer.</param>
+        public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
+        {
+            return serializer.Deserialize<ManifestContentPackFor>(reader);
+        }
+
+        /// <summary>Writes the JSON representation of the object.</summary>
+        /// <param name="writer">The JSON writer.</param>
+        /// <param name="value">The value.</param>
+        /// <param name="serializer">The calling serializer.</param>
+        public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
+        {
+            throw new InvalidOperationException("This converter does not write JSON.");
+        }
+    }
+}
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/ManifestDependencyArrayConverter.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/ManifestDependencyArrayConverter.cs
new file mode 100644
index 00000000..0a304ee3
--- /dev/null
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/ManifestDependencyArrayConverter.cs
@@ -0,0 +1,60 @@
+using System;
+using System.Collections.Generic;
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+using StardewModdingAPI.Toolkit.Serialisation.Models;
+
+namespace StardewModdingAPI.Toolkit.Serialisation.Converters
+{
+    /// <summary>Handles deserialisation of <see cref="ManifestDependency"/> arrays.</summary>
+    internal class ManifestDependencyArrayConverter : JsonConverter
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>Whether this converter can write JSON.</summary>
+        public override bool CanWrite => false;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Get whether this instance can convert the specified object type.</summary>
+        /// <param name="objectType">The object type.</param>
+        public override bool CanConvert(Type objectType)
+        {
+            return objectType == typeof(ManifestDependency[]);
+        }
+
+
+        /*********
+        ** Protected methods
+        *********/
+        /// <summary>Read the JSON representation of the object.</summary>
+        /// <param name="reader">The JSON reader.</param>
+        /// <param name="objectType">The object type.</param>
+        /// <param name="existingValue">The object being read.</param>
+        /// <param name="serializer">The calling serializer.</param>
+        public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
+        {
+            List<ManifestDependency> result = new List<ManifestDependency>();
+            foreach (JObject obj in JArray.Load(reader).Children<JObject>())
+            {
+                string uniqueID = obj.ValueIgnoreCase<string>(nameof(ManifestDependency.UniqueID));
+                string minVersion = obj.ValueIgnoreCase<string>(nameof(ManifestDependency.MinimumVersion));
+                bool required = obj.ValueIgnoreCase<bool?>(nameof(ManifestDependency.IsRequired)) ?? true;
+                result.Add(new ManifestDependency(uniqueID, minVersion, required));
+            }
+            return result.ToArray();
+        }
+
+        /// <summary>Writes the JSON representation of the object.</summary>
+        /// <param name="writer">The JSON writer.</param>
+        /// <param name="value">The value.</param>
+        /// <param name="serializer">The calling serializer.</param>
+        public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
+        {
+            throw new InvalidOperationException("This converter does not write JSON.");
+        }
+    }
+}
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
new file mode 100644
index 00000000..2075d27e
--- /dev/null
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
@@ -0,0 +1,36 @@
+using Newtonsoft.Json.Linq;
+using StardewModdingAPI.Toolkit.Serialisation.Models;
+
+namespace StardewModdingAPI.Toolkit.Serialisation.Converters
+{
+    /// <summary>Handles deserialisation of <see cref="SemanticVersion"/>.</summary>
+    internal class SemanticVersionConverter : SimpleReadOnlyConverter<SemanticVersion>
+    {
+        /*********
+        ** Protected methods
+        *********/
+        /// <summary>Read a JSON object.</summary>
+        /// <param name="obj">The JSON object to read.</param>
+        /// <param name="path">The path to the current JSON node.</param>
+        protected override SemanticVersion ReadObject(JObject obj, string path)
+        {
+            int major = obj.ValueIgnoreCase<int>("MajorVersion");
+            int minor = obj.ValueIgnoreCase<int>("MinorVersion");
+            int patch = obj.ValueIgnoreCase<int>("PatchVersion");
+            string build = obj.ValueIgnoreCase<string>("Build");
+            return new LegacyManifestVersion(major, minor, patch, build);
+        }
+
+        /// <summary>Read a JSON string.</summary>
+        /// <param name="str">The JSON string value.</param>
+        /// <param name="path">The path to the current JSON node.</param>
+        protected override SemanticVersion ReadString(string str, string path)
+        {
+            if (string.IsNullOrWhiteSpace(str))
+                return null;
+            if (!SemanticVersion.TryParse(str, out ISemanticVersion version))
+                throw new SParseException($"Can't parse semantic version from invalid value '{str}', should be formatted like 1.2, 1.2.30, or 1.2.30-beta (path: {path}).");
+            return (SemanticVersion)version;
+        }
+    }
+}
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SimpleReadOnlyConverter.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SimpleReadOnlyConverter.cs
new file mode 100644
index 00000000..5e0b0f4a
--- /dev/null
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SimpleReadOnlyConverter.cs
@@ -0,0 +1,76 @@
+using System;
+using Newtonsoft.Json;
+using Newtonsoft.Json.Linq;
+
+namespace StardewModdingAPI.Toolkit.Serialisation.Converters
+{
+    /// <summary>The base implementation for simplified converters which deserialise <typeparamref name="T"/> without overriding serialisation.</summary>
+    /// <typeparam name="T">The type to deserialise.</typeparam>
+    internal abstract class SimpleReadOnlyConverter<T> : JsonConverter
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>Whether this converter can write JSON.</summary>
+        public override bool CanWrite => false;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Get whether this instance can convert the specified object type.</summary>
+        /// <param name="objectType">The object type.</param>
+        public override bool CanConvert(Type objectType)
+        {
+            return objectType == typeof(T);
+        }
+
+        /// <summary>Writes the JSON representation of the object.</summary>
+        /// <param name="writer">The JSON writer.</param>
+        /// <param name="value">The value.</param>
+        /// <param name="serializer">The calling serializer.</param>
+        public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
+        {
+            throw new InvalidOperationException("This converter does not write JSON.");
+        }
+
+        /// <summary>Reads the JSON representation of the object.</summary>
+        /// <param name="reader">The JSON reader.</param>
+        /// <param name="objectType">The object type.</param>
+        /// <param name="existingValue">The object being read.</param>
+        /// <param name="serializer">The calling serializer.</param>
+        public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
+        {
+            string path = reader.Path;
+            switch (reader.TokenType)
+            {
+                case JsonToken.StartObject:
+                    return this.ReadObject(JObject.Load(reader), path);
+                case JsonToken.String:
+                    return this.ReadString(JToken.Load(reader).Value<string>(), path);
+                default:
+                    throw new SParseException($"Can't parse {typeof(T).Name} from {reader.TokenType} node (path: {reader.Path}).");
+            }
+        }
+
+
+        /*********
+        ** Protected methods
+        *********/
+        /// <summary>Read a JSON object.</summary>
+        /// <param name="obj">The JSON object to read.</param>
+        /// <param name="path">The path to the current JSON node.</param>
+        protected virtual T ReadObject(JObject obj, string path)
+        {
+            throw new SParseException($"Can't parse {typeof(T).Name} from object node (path: {path}).");
+        }
+
+        /// <summary>Read a JSON string.</summary>
+        /// <param name="str">The JSON string value.</param>
+        /// <param name="path">The path to the current JSON node.</param>
+        protected virtual T ReadString(string str, string path)
+        {
+            throw new SParseException($"Can't parse {typeof(T).Name} from string node (path: {path}).");
+        }
+    }
+}
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/StringEnumConverter.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/StringEnumConverter.cs
new file mode 100644
index 00000000..13e6e3a1
--- /dev/null
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/StringEnumConverter.cs
@@ -0,0 +1,22 @@
+using System;
+using Newtonsoft.Json.Converters;
+
+namespace StardewModdingAPI.Toolkit.Serialisation.Converters
+{
+    /// <summary>A variant of <see cref="StringEnumConverter"/> which only converts a specified enum.</summary>
+    /// <typeparam name="T">The enum type.</typeparam>
+    internal class StringEnumConverter<T> : StringEnumConverter
+    {
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Get whether this instance can convert the specified object type.</summary>
+        /// <param name="type">The object type.</param>
+        public override bool CanConvert(Type type)
+        {
+            return
+                base.CanConvert(type)
+                && (Nullable.GetUnderlyingType(type) ?? type) == typeof(T);
+        }
+    }
+}
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/InternalExtensions.cs b/src/StardewModdingAPI.Toolkit/Serialisation/InternalExtensions.cs
new file mode 100644
index 00000000..12b2c933
--- /dev/null
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/InternalExtensions.cs
@@ -0,0 +1,21 @@
+using System;
+using Newtonsoft.Json.Linq;
+
+namespace StardewModdingAPI.Toolkit.Serialisation
+{
+    /// <summary>Provides extension methods for parsing JSON.</summary>
+    public static class JsonExtensions
+    {
+        /// <summary>Get a JSON field value from a case-insensitive field name. This will check for an exact match first, then search without case sensitivity.</summary>
+        /// <typeparam name="T">The value type.</typeparam>
+        /// <param name="obj">The JSON object to search.</param>
+        /// <param name="fieldName">The field name.</param>
+        public static T ValueIgnoreCase<T>(this JObject obj, string fieldName)
+        {
+            JToken token = obj.GetValue(fieldName, StringComparison.InvariantCultureIgnoreCase);
+            return token != null
+                ? token.Value<T>()
+                : default(T);
+        }
+    }
+}
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/JsonHelper.cs b/src/StardewModdingAPI.Toolkit/Serialisation/JsonHelper.cs
new file mode 100644
index 00000000..00f334ad
--- /dev/null
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/JsonHelper.cs
@@ -0,0 +1,123 @@
+using System;
+using System.Collections.Generic;
+using System.IO;
+using Newtonsoft.Json;
+using StardewModdingAPI.Toolkit.Serialisation.Converters;
+
+namespace StardewModdingAPI.Toolkit.Serialisation
+{
+    /// <summary>Encapsulates SMAPI's JSON file parsing.</summary>
+    public class JsonHelper
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The JSON settings to use when serialising and deserialising files.</summary>
+        public JsonSerializerSettings JsonSettings { get; } = new JsonSerializerSettings
+        {
+            Formatting = Formatting.Indented,
+            ObjectCreationHandling = ObjectCreationHandling.Replace, // avoid issue where default ICollection<T> values are duplicated each time the config is loaded
+            Converters = new List<JsonConverter> { new SemanticVersionConverter() }
+        };
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Read a JSON file.</summary>
+        /// <typeparam name="TModel">The model type.</typeparam>
+        /// <param name="fullPath">The absolete file path.</param>
+        /// <returns>Returns the deserialised model, or <c>null</c> if the file doesn't exist or is empty.</returns>
+        /// <exception cref="InvalidOperationException">The given path is empty or invalid.</exception>
+        public TModel ReadJsonFile<TModel>(string fullPath)
+            where TModel : class
+        {
+            // validate
+            if (string.IsNullOrWhiteSpace(fullPath))
+                throw new ArgumentException("The file path is empty or invalid.", nameof(fullPath));
+
+            // read file
+            string json;
+            try
+            {
+                json = File.ReadAllText(fullPath);
+            }
+            catch (Exception ex) when (ex is DirectoryNotFoundException || ex is FileNotFoundException)
+            {
+                return null;
+            }
+
+            // deserialise model
+            try
+            {
+                return this.Deserialise<TModel>(json);
+            }
+            catch (Exception ex)
+            {
+                string error = $"Can't parse JSON file at {fullPath}.";
+
+                if (ex is JsonReaderException)
+                {
+                    error += " This doesn't seem to be valid JSON.";
+                    if (json.Contains("“") || json.Contains("”"))
+                        error += " Found curly quotes in the text; note that only straight quotes are allowed in JSON.";
+                }
+                error += $"\nTechnical details: {ex.Message}";
+                throw new JsonReaderException(error);
+            }
+        }
+
+        /// <summary>Save to a JSON file.</summary>
+        /// <typeparam name="TModel">The model type.</typeparam>
+        /// <param name="fullPath">The absolete file path.</param>
+        /// <param name="model">The model to save.</param>
+        /// <exception cref="InvalidOperationException">The given path is empty or invalid.</exception>
+        public void WriteJsonFile<TModel>(string fullPath, TModel model)
+            where TModel : class
+        {
+            // validate
+            if (string.IsNullOrWhiteSpace(fullPath))
+                throw new ArgumentException("The file path is empty or invalid.", nameof(fullPath));
+
+            // create directory if needed
+            string dir = Path.GetDirectoryName(fullPath);
+            if (dir == null)
+                throw new ArgumentException("The file path is invalid.", nameof(fullPath));
+            if (!Directory.Exists(dir))
+                Directory.CreateDirectory(dir);
+
+            // write file
+            string json = JsonConvert.SerializeObject(model, this.JsonSettings);
+            File.WriteAllText(fullPath, json);
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>Deserialize JSON text if possible.</summary>
+        /// <typeparam name="TModel">The model type.</typeparam>
+        /// <param name="json">The raw JSON text.</param>
+        private TModel Deserialise<TModel>(string json)
+        {
+            try
+            {
+                return JsonConvert.DeserializeObject<TModel>(json, this.JsonSettings);
+            }
+            catch (JsonReaderException)
+            {
+                // try replacing curly quotes
+                if (json.Contains("“") || json.Contains("”"))
+                {
+                    try
+                    {
+                        return JsonConvert.DeserializeObject<TModel>(json.Replace('“', '"').Replace('”', '"'), this.JsonSettings);
+                    }
+                    catch { /* rethrow original error */ }
+                }
+
+                throw;
+            }
+        }
+    }
+}
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Models/LegacyManifestVersion.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Models/LegacyManifestVersion.cs
new file mode 100644
index 00000000..12f6755b
--- /dev/null
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Models/LegacyManifestVersion.cs
@@ -0,0 +1,26 @@
+using Newtonsoft.Json;
+
+namespace StardewModdingAPI.Toolkit.Serialisation.Models
+{
+    /// <summary>An implementation of <see cref="ISemanticVersion"/> that hamdles the legacy <see cref="Manifest"/> version format.</summary>
+    public class LegacyManifestVersion : SemanticVersion
+    {
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="majorVersion">The major version incremented for major API changes.</param>
+        /// <param name="minorVersion">The minor version incremented for backwards-compatible changes.</param>
+        /// <param name="patchVersion">The patch version for backwards-compatible bug fixes.</param>
+        /// <param name="build">An optional build tag.</param>
+        [JsonConstructor]
+        public LegacyManifestVersion(int majorVersion, int minorVersion, int patchVersion, string build = null)
+            : base(
+                majorVersion,
+                minorVersion,
+                patchVersion,
+                build != "0" ? build : null // '0' from incorrect examples in old SMAPI documentation
+            )
+        { }
+    }
+}
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs
new file mode 100644
index 00000000..68987dd1
--- /dev/null
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs
@@ -0,0 +1,49 @@
+using System.Collections.Generic;
+using Newtonsoft.Json;
+using StardewModdingAPI.Toolkit.Serialisation.Converters;
+
+namespace StardewModdingAPI.Toolkit.Serialisation.Models
+{
+    /// <summary>A manifest which describes a mod for SMAPI.</summary>
+    public class Manifest
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The mod name.</summary>
+        public string Name { get; set; }
+
+        /// <summary>A brief description of the mod.</summary>
+        public string Description { get; set; }
+
+        /// <summary>The mod author's name.</summary>
+        public string Author { get; set; }
+
+        /// <summary>The mod version.</summary>
+        public SemanticVersion Version { get; set; }
+
+        /// <summary>The minimum SMAPI version required by this mod, if any.</summary>
+        public SemanticVersion MinimumApiVersion { get; set; }
+
+        /// <summary>The name of the DLL in the directory that has the <c>Entry</c> method. Mutually exclusive with <see cref="ContentPackFor"/>.</summary>
+        public string EntryDll { get; set; }
+
+        /// <summary>The mod which will read this as a content pack. Mutually exclusive with <see cref="Manifest.EntryDll"/>.</summary>
+        [JsonConverter(typeof(ManifestContentPackForConverter))]
+        public ManifestContentPackFor ContentPackFor { get; set; }
+
+        /// <summary>The other mods that must be loaded before this mod.</summary>
+        [JsonConverter(typeof(ManifestDependencyArrayConverter))]
+        public ManifestDependency[] Dependencies { get; set; }
+
+        /// <summary>The namespaced mod IDs to query for updates (like <c>Nexus:541</c>).</summary>
+        public string[] UpdateKeys { get; set; }
+
+        /// <summary>The unique mod ID.</summary>
+        public string UniqueID { get; set; }
+
+        /// <summary>Any manifest fields which didn't match a valid field.</summary>
+        [JsonExtensionData]
+        public IDictionary<string, object> ExtraFields { get; set; }
+    }
+}
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestContentPackFor.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestContentPackFor.cs
new file mode 100644
index 00000000..00546533
--- /dev/null
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestContentPackFor.cs
@@ -0,0 +1,15 @@
+namespace StardewModdingAPI.Toolkit.Serialisation.Models
+{
+    /// <summary>Indicates which mod can read the content pack represented by the containing manifest.</summary>
+    public class ManifestContentPackFor
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The unique ID of the mod which can read this content pack.</summary>
+        public string UniqueID { get; set; }
+
+        /// <summary>The minimum required version (if any).</summary>
+        public SemanticVersion MinimumVersion { get; set; }
+    }
+}
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestDependency.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestDependency.cs
new file mode 100644
index 00000000..d902f9ac
--- /dev/null
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestDependency.cs
@@ -0,0 +1,35 @@
+namespace StardewModdingAPI.Toolkit.Serialisation.Models
+{
+    /// <summary>A mod dependency listed in a mod manifest.</summary>
+    public class ManifestDependency
+    {
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The unique mod ID to require.</summary>
+        public string UniqueID { get; set; }
+
+        /// <summary>The minimum required version (if any).</summary>
+        public SemanticVersion MinimumVersion { get; set; }
+
+        /// <summary>Whether the dependency must be installed to use the mod.</summary>
+        public bool IsRequired { get; set; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="uniqueID">The unique mod ID to require.</param>
+        /// <param name="minimumVersion">The minimum required version (if any).</param>
+        /// <param name="required">Whether the dependency must be installed to use the mod.</param>
+        public ManifestDependency(string uniqueID, string minimumVersion, bool required = true)
+        {
+            this.UniqueID = uniqueID;
+            this.MinimumVersion = !string.IsNullOrWhiteSpace(minimumVersion)
+                ? new SemanticVersion(minimumVersion)
+                : null;
+            this.IsRequired = required;
+        }
+    }
+}
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/SParseException.cs b/src/StardewModdingAPI.Toolkit/Serialisation/SParseException.cs
new file mode 100644
index 00000000..61a7b305
--- /dev/null
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/SParseException.cs
@@ -0,0 +1,17 @@
+using System;
+
+namespace StardewModdingAPI.Toolkit.Serialisation
+{
+    /// <summary>A format exception which provides a user-facing error message.</summary>
+    internal class SParseException : FormatException
+    {
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="message">The error message.</param>
+        /// <param name="ex">The underlying exception, if any.</param>
+        public SParseException(string message, Exception ex = null)
+            : base(message, ex) { }
+    }
+}
-- 
cgit 


From 6eba10948bf39d5e05505ec060f6920f84610d58 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <github@jplamondonw.com>
Date: Tue, 5 Jun 2018 23:03:26 -0400
Subject: fix version parsing issues in new toolkit code (#532)

---
 .../Converters/SemanticVersionConverter.cs         |  5 ++++-
 .../Serialisation/Models/LegacyManifestVersion.cs  | 26 ----------------------
 2 files changed, 4 insertions(+), 27 deletions(-)
 delete mode 100644 src/StardewModdingAPI.Toolkit/Serialisation/Models/LegacyManifestVersion.cs

(limited to 'src/StardewModdingAPI.Toolkit/Serialisation')

diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
index 2075d27e..2ddaa1bf 100644
--- a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
@@ -18,7 +18,10 @@ namespace StardewModdingAPI.Toolkit.Serialisation.Converters
             int minor = obj.ValueIgnoreCase<int>("MinorVersion");
             int patch = obj.ValueIgnoreCase<int>("PatchVersion");
             string build = obj.ValueIgnoreCase<string>("Build");
-            return new LegacyManifestVersion(major, minor, patch, build);
+            if (build == "0")
+                build = null; // '0' from incorrect examples in old SMAPI documentation
+
+            return new SemanticVersion(major, minor, patch, build);
         }
 
         /// <summary>Read a JSON string.</summary>
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Models/LegacyManifestVersion.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Models/LegacyManifestVersion.cs
deleted file mode 100644
index 12f6755b..00000000
--- a/src/StardewModdingAPI.Toolkit/Serialisation/Models/LegacyManifestVersion.cs
+++ /dev/null
@@ -1,26 +0,0 @@
-using Newtonsoft.Json;
-
-namespace StardewModdingAPI.Toolkit.Serialisation.Models
-{
-    /// <summary>An implementation of <see cref="ISemanticVersion"/> that hamdles the legacy <see cref="Manifest"/> version format.</summary>
-    public class LegacyManifestVersion : SemanticVersion
-    {
-        /*********
-        ** Public methods
-        *********/
-        /// <summary>Construct an instance.</summary>
-        /// <param name="majorVersion">The major version incremented for major API changes.</param>
-        /// <param name="minorVersion">The minor version incremented for backwards-compatible changes.</param>
-        /// <param name="patchVersion">The patch version for backwards-compatible bug fixes.</param>
-        /// <param name="build">An optional build tag.</param>
-        [JsonConstructor]
-        public LegacyManifestVersion(int majorVersion, int minorVersion, int patchVersion, string build = null)
-            : base(
-                majorVersion,
-                minorVersion,
-                patchVersion,
-                build != "0" ? build : null // '0' from incorrect examples in old SMAPI documentation
-            )
-        { }
-    }
-}
-- 
cgit 


From b08e27d13a1f0c82656df95212fc40588b3b5314 Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <github@jplamondonw.com>
Date: Sun, 24 Jun 2018 21:51:51 -0400
Subject: merge IManifest interfaces into new project (#532)

---
 .../Converters/SemanticVersionConverter.cs         |  1 -
 .../Serialisation/Models/Manifest.cs               | 37 +++++++++++++++++++---
 .../Serialisation/Models/ManifestContentPackFor.cs |  8 +++--
 .../Serialisation/Models/ManifestDependency.cs     |  8 +++--
 4 files changed, 44 insertions(+), 10 deletions(-)

(limited to 'src/StardewModdingAPI.Toolkit/Serialisation')

diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
index 2ddaa1bf..eff95d1f 100644
--- a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
@@ -1,5 +1,4 @@
 using Newtonsoft.Json.Linq;
-using StardewModdingAPI.Toolkit.Serialisation.Models;
 
 namespace StardewModdingAPI.Toolkit.Serialisation.Converters
 {
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs
index 68987dd1..6ec57258 100644
--- a/src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs
@@ -5,7 +5,7 @@ using StardewModdingAPI.Toolkit.Serialisation.Converters;
 namespace StardewModdingAPI.Toolkit.Serialisation.Models
 {
     /// <summary>A manifest which describes a mod for SMAPI.</summary>
-    public class Manifest
+    public class Manifest : IManifest
     {
         /*********
         ** Accessors
@@ -20,21 +20,23 @@ namespace StardewModdingAPI.Toolkit.Serialisation.Models
         public string Author { get; set; }
 
         /// <summary>The mod version.</summary>
-        public SemanticVersion Version { get; set; }
+        [JsonConverter(typeof(SemanticVersionConverter))]
+        public ISemanticVersion Version { get; set; }
 
         /// <summary>The minimum SMAPI version required by this mod, if any.</summary>
-        public SemanticVersion MinimumApiVersion { get; set; }
+        [JsonConverter(typeof(SemanticVersionConverter))]
+        public ISemanticVersion MinimumApiVersion { get; set; }
 
         /// <summary>The name of the DLL in the directory that has the <c>Entry</c> method. Mutually exclusive with <see cref="ContentPackFor"/>.</summary>
         public string EntryDll { get; set; }
 
         /// <summary>The mod which will read this as a content pack. Mutually exclusive with <see cref="Manifest.EntryDll"/>.</summary>
         [JsonConverter(typeof(ManifestContentPackForConverter))]
-        public ManifestContentPackFor ContentPackFor { get; set; }
+        public IManifestContentPackFor ContentPackFor { get; set; }
 
         /// <summary>The other mods that must be loaded before this mod.</summary>
         [JsonConverter(typeof(ManifestDependencyArrayConverter))]
-        public ManifestDependency[] Dependencies { get; set; }
+        public IManifestDependency[] Dependencies { get; set; }
 
         /// <summary>The namespaced mod IDs to query for updates (like <c>Nexus:541</c>).</summary>
         public string[] UpdateKeys { get; set; }
@@ -45,5 +47,30 @@ namespace StardewModdingAPI.Toolkit.Serialisation.Models
         /// <summary>Any manifest fields which didn't match a valid field.</summary>
         [JsonExtensionData]
         public IDictionary<string, object> ExtraFields { get; set; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        public Manifest() { }
+
+        /// <summary>Construct an instance for a transitional content pack.</summary>
+        /// <param name="uniqueID">The unique mod ID.</param>
+        /// <param name="name">The mod name.</param>
+        /// <param name="author">The mod author's name.</param>
+        /// <param name="description">A brief description of the mod.</param>
+        /// <param name="version">The mod version.</param>
+        /// <param name="contentPackFor">The modID which will read this as a content pack.</param>
+        public Manifest(string uniqueID, string name, string author, string description, ISemanticVersion version, string contentPackFor = null)
+        {
+            this.Name = name;
+            this.Author = author;
+            this.Description = description;
+            this.Version = version;
+            this.UniqueID = uniqueID;
+            this.UpdateKeys = new string[0];
+            this.ContentPackFor = new ManifestContentPackFor { UniqueID = contentPackFor };
+        }
     }
 }
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestContentPackFor.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestContentPackFor.cs
index 00546533..64808dcf 100644
--- a/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestContentPackFor.cs
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestContentPackFor.cs
@@ -1,7 +1,10 @@
+using Newtonsoft.Json;
+using StardewModdingAPI.Toolkit.Serialisation.Converters;
+
 namespace StardewModdingAPI.Toolkit.Serialisation.Models
 {
     /// <summary>Indicates which mod can read the content pack represented by the containing manifest.</summary>
-    public class ManifestContentPackFor
+    public class ManifestContentPackFor : IManifestContentPackFor
     {
         /*********
         ** Accessors
@@ -10,6 +13,7 @@ namespace StardewModdingAPI.Toolkit.Serialisation.Models
         public string UniqueID { get; set; }
 
         /// <summary>The minimum required version (if any).</summary>
-        public SemanticVersion MinimumVersion { get; set; }
+        [JsonConverter(typeof(SemanticVersionConverter))]
+        public ISemanticVersion MinimumVersion { get; set; }
     }
 }
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestDependency.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestDependency.cs
index d902f9ac..67e733dd 100644
--- a/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestDependency.cs
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestDependency.cs
@@ -1,7 +1,10 @@
+using Newtonsoft.Json;
+using StardewModdingAPI.Toolkit.Serialisation.Converters;
+
 namespace StardewModdingAPI.Toolkit.Serialisation.Models
 {
     /// <summary>A mod dependency listed in a mod manifest.</summary>
-    public class ManifestDependency
+    public class ManifestDependency : IManifestDependency
     {
         /*********
         ** Accessors
@@ -10,7 +13,8 @@ namespace StardewModdingAPI.Toolkit.Serialisation.Models
         public string UniqueID { get; set; }
 
         /// <summary>The minimum required version (if any).</summary>
-        public SemanticVersion MinimumVersion { get; set; }
+        [JsonConverter(typeof(SemanticVersionConverter))]
+        public ISemanticVersion MinimumVersion { get; set; }
 
         /// <summary>Whether the dependency must be installed to use the mod.</summary>
         public bool IsRequired { get; set; }
-- 
cgit 


From 85efb3112912a28dbdc82b18d0be8dd117f8c8ee Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <github@jplamondonw.com>
Date: Sun, 24 Jun 2018 23:01:39 -0400
Subject: fix ISemanticVersion deserialisation errors (#532)

---
 .../Serialisation/Converters/SemanticVersionConverter.cs          | 8 ++++----
 src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs    | 2 --
 .../Serialisation/Models/ManifestContentPackFor.cs                | 4 ----
 .../Serialisation/Models/ManifestDependency.cs                    | 4 ----
 4 files changed, 4 insertions(+), 14 deletions(-)

(limited to 'src/StardewModdingAPI.Toolkit/Serialisation')

diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
index eff95d1f..4f0949fa 100644
--- a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
@@ -2,8 +2,8 @@ using Newtonsoft.Json.Linq;
 
 namespace StardewModdingAPI.Toolkit.Serialisation.Converters
 {
-    /// <summary>Handles deserialisation of <see cref="SemanticVersion"/>.</summary>
-    internal class SemanticVersionConverter : SimpleReadOnlyConverter<SemanticVersion>
+    /// <summary>Handles deserialisation of <see cref="ISemanticVersion"/>.</summary>
+    internal class SemanticVersionConverter : SimpleReadOnlyConverter<ISemanticVersion>
     {
         /*********
         ** Protected methods
@@ -11,7 +11,7 @@ namespace StardewModdingAPI.Toolkit.Serialisation.Converters
         /// <summary>Read a JSON object.</summary>
         /// <param name="obj">The JSON object to read.</param>
         /// <param name="path">The path to the current JSON node.</param>
-        protected override SemanticVersion ReadObject(JObject obj, string path)
+        protected override ISemanticVersion ReadObject(JObject obj, string path)
         {
             int major = obj.ValueIgnoreCase<int>("MajorVersion");
             int minor = obj.ValueIgnoreCase<int>("MinorVersion");
@@ -26,7 +26,7 @@ namespace StardewModdingAPI.Toolkit.Serialisation.Converters
         /// <summary>Read a JSON string.</summary>
         /// <param name="str">The JSON string value.</param>
         /// <param name="path">The path to the current JSON node.</param>
-        protected override SemanticVersion ReadString(string str, string path)
+        protected override ISemanticVersion ReadString(string str, string path)
         {
             if (string.IsNullOrWhiteSpace(str))
                 return null;
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs
index 6ec57258..6cb9496b 100644
--- a/src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Models/Manifest.cs
@@ -20,11 +20,9 @@ namespace StardewModdingAPI.Toolkit.Serialisation.Models
         public string Author { get; set; }
 
         /// <summary>The mod version.</summary>
-        [JsonConverter(typeof(SemanticVersionConverter))]
         public ISemanticVersion Version { get; set; }
 
         /// <summary>The minimum SMAPI version required by this mod, if any.</summary>
-        [JsonConverter(typeof(SemanticVersionConverter))]
         public ISemanticVersion MinimumApiVersion { get; set; }
 
         /// <summary>The name of the DLL in the directory that has the <c>Entry</c> method. Mutually exclusive with <see cref="ContentPackFor"/>.</summary>
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestContentPackFor.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestContentPackFor.cs
index 64808dcf..d0e42216 100644
--- a/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestContentPackFor.cs
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestContentPackFor.cs
@@ -1,6 +1,3 @@
-using Newtonsoft.Json;
-using StardewModdingAPI.Toolkit.Serialisation.Converters;
-
 namespace StardewModdingAPI.Toolkit.Serialisation.Models
 {
     /// <summary>Indicates which mod can read the content pack represented by the containing manifest.</summary>
@@ -13,7 +10,6 @@ namespace StardewModdingAPI.Toolkit.Serialisation.Models
         public string UniqueID { get; set; }
 
         /// <summary>The minimum required version (if any).</summary>
-        [JsonConverter(typeof(SemanticVersionConverter))]
         public ISemanticVersion MinimumVersion { get; set; }
     }
 }
diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestDependency.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestDependency.cs
index 67e733dd..8db58d5d 100644
--- a/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestDependency.cs
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Models/ManifestDependency.cs
@@ -1,6 +1,3 @@
-using Newtonsoft.Json;
-using StardewModdingAPI.Toolkit.Serialisation.Converters;
-
 namespace StardewModdingAPI.Toolkit.Serialisation.Models
 {
     /// <summary>A mod dependency listed in a mod manifest.</summary>
@@ -13,7 +10,6 @@ namespace StardewModdingAPI.Toolkit.Serialisation.Models
         public string UniqueID { get; set; }
 
         /// <summary>The minimum required version (if any).</summary>
-        [JsonConverter(typeof(SemanticVersionConverter))]
         public ISemanticVersion MinimumVersion { get; set; }
 
         /// <summary>Whether the dependency must be installed to use the mod.</summary>
-- 
cgit 


From 89ad599561a058289d8ea44e0c345f1a30a3a6ac Mon Sep 17 00:00:00 2001
From: Jesse Plamondon-Willard <github@jplamondonw.com>
Date: Thu, 28 Jun 2018 21:41:00 -0400
Subject: add support for writing versions to JSON

---
 .../Converters/SemanticVersionConverter.cs         | 60 ++++++++++++++++++++--
 1 file changed, 55 insertions(+), 5 deletions(-)

(limited to 'src/StardewModdingAPI.Toolkit/Serialisation')

diff --git a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
index 4f0949fa..9b2f5e7d 100644
--- a/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
+++ b/src/StardewModdingAPI.Toolkit/Serialisation/Converters/SemanticVersionConverter.cs
@@ -1,17 +1,67 @@
+using System;
+using Newtonsoft.Json;
 using Newtonsoft.Json.Linq;
 
 namespace StardewModdingAPI.Toolkit.Serialisation.Converters
 {
     /// <summary>Handles deserialisation of <see cref="ISemanticVersion"/>.</summary>
-    internal class SemanticVersionConverter : SimpleReadOnlyConverter<ISemanticVersion>
+    internal class SemanticVersionConverter : JsonConverter
     {
         /*********
-        ** Protected methods
+        ** Accessors
+        *********/
+        /// <summary>Get whether this converter can read JSON.</summary>
+        public override bool CanRead => true;
+
+        /// <summary>Get whether this converter can write JSON.</summary>
+        public override bool CanWrite => true;
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Get whether this instance can convert the specified object type.</summary>
+        /// <param name="objectType">The object type.</param>
+        public override bool CanConvert(Type objectType)
+        {
+            return typeof(ISemanticVersion).IsAssignableFrom(objectType);
+        }
+
+        /// <summary>Reads the JSON representation of the object.</summary>
+        /// <param name="reader">The JSON reader.</param>
+        /// <param name="objectType">The object type.</param>
+        /// <param name="existingValue">The object being read.</param>
+        /// <param name="serializer">The calling serializer.</param>
+        public override object ReadJson(JsonReader reader, Type objectType, object existingValue, JsonSerializer serializer)
+        {
+            string path = reader.Path;
+            switch (reader.TokenType)
+            {
+                case JsonToken.StartObject:
+                    return this.ReadObject(JObject.Load(reader));
+                case JsonToken.String:
+                    return this.ReadString(JToken.Load(reader).Value<string>(), path);
+                default:
+                    throw new SParseException($"Can't parse {nameof(ISemanticVersion)} from {reader.TokenType} node (path: {reader.Path}).");
+            }
+        }
+
+        /// <summary>Writes the JSON representation of the object.</summary>
+        /// <param name="writer">The JSON writer.</param>
+        /// <param name="value">The value.</param>
+        /// <param name="serializer">The calling serializer.</param>
+        public override void WriteJson(JsonWriter writer, object value, JsonSerializer serializer)
+        {
+            writer.WriteValue(value?.ToString());
+        }
+
+
+        /*********
+        ** Private methods
         *********/
         /// <summary>Read a JSON object.</summary>
         /// <param name="obj">The JSON object to read.</param>
-        /// <param name="path">The path to the current JSON node.</param>
-        protected override ISemanticVersion ReadObject(JObject obj, string path)
+        private ISemanticVersion ReadObject(JObject obj)
         {
             int major = obj.ValueIgnoreCase<int>("MajorVersion");
             int minor = obj.ValueIgnoreCase<int>("MinorVersion");
@@ -26,7 +76,7 @@ namespace StardewModdingAPI.Toolkit.Serialisation.Converters
         /// <summary>Read a JSON string.</summary>
         /// <param name="str">The JSON string value.</param>
         /// <param name="path">The path to the current JSON node.</param>
-        protected override ISemanticVersion ReadString(string str, string path)
+        private ISemanticVersion ReadString(string str, string path)
         {
             if (string.IsNullOrWhiteSpace(str))
                 return null;
-- 
cgit