1 files changed, 142 insertions, 0 deletions
diff --git a/src/StardewModdingAPI/Framework/ContentEventHelper.cs b/src/StardewModdingAPI/Framework/ContentEventHelper.cs
new file mode 100644
index 00000000..d4a9bbb8
--- /dev/null
+++ b/src/StardewModdingAPI/Framework/ContentEventHelper.cs
@@ -0,0 +1,142 @@
+using System;
+using System.Collections.Generic;
+using System.Text.RegularExpressions;
+using Microsoft.Xna.Framework.Graphics;
+
+namespace StardewModdingAPI.Framework
+{
+    /// <summary>Encapsulates access and changes to content being read from a data file.</summary>
+    internal class ContentEventHelper : EventArgs, IContentEventHelper
+    {
+        /*********
+        ** Properties
+        *********/
+        /// <summary>Normalises an asset key to match the cache key.</summary>
+        private readonly Func<string, string> GetNormalisedPath;
+
+
+        /*********
+        ** Accessors
+        *********/
+        /// <summary>The normalised asset path being read. The format may change between platforms; see <see cref="IsPath"/> to compare with a known path.</summary>
+        public string Path { get; }
+
+        /// <summary>The content data being read.</summary>
+        public object Data { get; private set; }
+
+
+        /*********
+        ** Public methods
+        *********/
+        /// <summary>Construct an instance.</summary>
+        /// <param name="path">The file path being read.</param>
+        /// <param name="data">The content data being read.</param>
+        /// <param name="getNormalisedPath">Normalises an asset key to match the cache key.</param>
+        public ContentEventHelper(string path, object data, Func<string, string> getNormalisedPath)
+        {
+            this.Path = path;
+            this.Data = data;
+            this.GetNormalisedPath = getNormalisedPath;
+        }
+
+        /// <summary>Get whether the asset path being loaded matches a given path after normalisation.</summary>
+        /// <param name="path">The expected asset path, relative to the game folder and without the .xnb extension (like 'Data\ObjectInformation').</param>
+        /// <param name="matchLocalisedVersion">Whether to match a localised version of the asset file (like 'Data\ObjectInformation.ja-JP').</param>
+        public bool IsPath(string path, bool matchLocalisedVersion = true)
+        {
+            path = this.GetNormalisedPath(path);
+
+            // equivalent
+            if (this.Path.Equals(path, StringComparison.InvariantCultureIgnoreCase))
+                return true;
+
+            // localised version
+            if (matchLocalisedVersion)
+            {
+                return
+                    this.Path.StartsWith($"{path}.", StringComparison.InvariantCultureIgnoreCase) // starts with given path
+                    && Regex.IsMatch(this.Path.Substring(path.Length + 1), "^[a-z]+-[A-Z]+$"); // ends with locale (e.g. pt-BR)
+            }
+
+            // no match
+            return false;
+        }
+
+        /// <summary>Get the data as a given type.</summary>
+        /// <typeparam name="TData">The expected data type.</typeparam>
+        /// <exception cref="InvalidCastException">The data can't be converted to <typeparamref name="TData"/>.</exception>
+        public TData GetData<TData>()
+        {
+            if (!(this.Data is TData))
+                throw new InvalidCastException($"The content data of type {this.Data.GetType().FullName} can't be converted to the requested {typeof(TData).FullName}.");
+            return (TData)this.Data;
+        }
+
+        /// <summary>Add or replace an entry in the dictionary data.</summary>
+        /// <typeparam name="TKey">The entry key type.</typeparam>
+        /// <typeparam name="TValue">The entry value type.</typeparam>
+        /// <param name="key">The entry key.</param>
+        /// <param name="value">The entry value.</param>
+        /// <exception cref="InvalidOperationException">The content being read isn't a dictionary.</exception>
+        public void SetDictionaryEntry<TKey, TValue>(TKey key, TValue value)
+        {
+            IDictionary<TKey, TValue> data = this.GetData<Dictionary<TKey, TValue>>();
+            data[key] = value;
+        }
+
+        /// <summary>Add or replace an entry in the dictionary data.</summary>
+        /// <typeparam name="TKey">The entry key type.</typeparam>
+        /// <typeparam name="TValue">The entry value type.</typeparam>
+        /// <param name="key">The entry key.</param>
+        /// <param name="value">A callback which accepts the current value and returns the new value.</param>
+        /// <exception cref="InvalidOperationException">The content being read isn't a dictionary.</exception>
+        public void SetDictionaryEntry<TKey, TValue>(TKey key, Func<TValue, TValue> value)
+        {
+            IDictionary<TKey, TValue> data = this.GetData<Dictionary<TKey, TValue>>();
+            data[key] = value(data[key]);
+        }
+
+        /// <summary>Replace the entire content value with the given value. This is generally not recommended, since it may break compatibility with other mods or different versions of the game.</summary>
+        /// <param name="value">The new content value.</param>
+        /// <exception cref="ArgumentNullException">The <paramref name="value"/> is null.</exception>
+        /// <exception cref="InvalidCastException">The <paramref name="value"/>'s type is not compatible with the loaded asset's type.</exception>
+        public void ReplaceWith(object value)
+        {
+            if (value == null)
+                throw new ArgumentNullException(nameof(value), "Can't set a loaded asset to a null value.");
+            if (!this.Data.GetType().IsInstanceOfType(value))
+                throw new InvalidCastException($"Can't replace loaded asset of type {this.GetFriendlyTypeName(this.Data.GetType())} with value of type {this.GetFriendlyTypeName(value.GetType())}. The new type must be compatible to prevent game errors.");
+
+            this.Data = value;
+        }
+
+
+        /*********
+        ** Private methods
+        *********/
+        /// <summary>Get a human-readable type name.</summary>
+        /// <param name="type">The type to name.</param>
+        private string GetFriendlyTypeName(Type type)
+        {
+            // dictionary
+            if (type.IsGenericType && type.GetGenericTypeDefinition() == typeof(Dictionary<,>))
+            {
+                Type[] genericArgs = type.GetGenericArguments();
+                return $"Dictionary<{this.GetFriendlyTypeName(genericArgs[0])}, {this.GetFriendlyTypeName(genericArgs[1])}>";
+            }
+
+            // texture
+            if (type == typeof(Texture2D))
+                return type.Name;
+
+            // native type
+            if (type == typeof(int))
+                return "int";
+            if (type == typeof(string))
+                return "string";
+
+            // default
+            return type.FullName;
+        }
+    }
+}