using System;
using System.IO;
using Newtonsoft.Json;
using StardewModdingAPI.Toolkit.Serialisation;
using StardewModdingAPI.Toolkit.Utilities;
using StardewValley;
namespace StardewModdingAPI.Framework.ModHelpers
{
/// Provides an API for reading and storing local mod data.
internal class DataHelper : BaseHelper, IDataHelper
{
/*********
** Properties
*********/
/// Encapsulates SMAPI's JSON file parsing.
private readonly JsonHelper JsonHelper;
/// The absolute path to the mod folder.
private readonly string ModFolderPath;
/*********
** Public methods
*********/
/// Construct an instance.
/// The unique ID of the relevant mod.
/// The absolute path to the mod folder.
/// The absolute path to the mod folder.
public DataHelper(string modID, string modFolderPath, JsonHelper jsonHelper)
: base(modID)
{
this.ModFolderPath = modFolderPath;
this.JsonHelper = jsonHelper;
}
/****
** JSON file
****/
/// Read data from a JSON file in the mod's folder.
/// The model type. This should be a plain class that has public properties for the data you want. The properties can be complex types.
/// The file path relative to the mod folder.
/// Returns the deserialised model, or null if the file doesn't exist or is empty.
/// The is not relative or contains directory climbing (../).
public TModel ReadJsonFile(string path) where TModel : class
{
if (!PathUtilities.IsSafeRelativePath(path))
throw new InvalidOperationException($"You must call {nameof(IModHelper.Data)}.{nameof(this.ReadJsonFile)} with a relative path.");
path = Path.Combine(this.ModFolderPath, PathUtilities.NormalisePathSeparators(path));
return this.JsonHelper.ReadJsonFileIfExists(path, out TModel data)
? data
: null;
}
/// Save data to a JSON file in the mod's folder.
/// The model type. This should be a plain class that has public properties for the data you want. The properties can be complex types.
/// The file path relative to the mod folder.
/// The arbitrary data to save.
/// The is not relative or contains directory climbing (../).
public void WriteJsonFile(string path, TModel data) where TModel : class
{
if (!PathUtilities.IsSafeRelativePath(path))
throw new InvalidOperationException($"You must call {nameof(IMod.Helper)}.{nameof(IModHelper.Data)}.{nameof(this.WriteJsonFile)} with a relative path (without directory climbing).");
path = Path.Combine(this.ModFolderPath, PathUtilities.NormalisePathSeparators(path));
this.JsonHelper.WriteJsonFile(path, data);
}
/****
** Save file
****/
/// Read arbitrary data stored in the current save slot. This is only possible if a save has been loaded.
/// The model type. This should be a plain class that has public properties for the data you want. The properties can be complex types.
/// The unique key identifying the data.
/// Returns the parsed data, or null if the entry doesn't exist or is empty.
/// The player hasn't loaded a save file yet or isn't the main player.
public TModel ReadSaveData(string key) where TModel : class
{
if (!Context.IsSaveLoaded)
throw new InvalidOperationException($"Can't use {nameof(IMod.Helper)}.{nameof(IModHelper.Data)}.{nameof(this.ReadSaveData)} when a save file isn't loaded.");
if (!Context.IsMainPlayer)
throw new InvalidOperationException($"Can't use {nameof(IMod.Helper)}.{nameof(IModHelper.Data)}.{nameof(this.ReadSaveData)} because this isn't the main player. (Save files are stored on the main player's computer.)");
return Game1.CustomData.TryGetValue(this.GetSaveFileKey(key), out string value)
? this.JsonHelper.Deserialise(value)
: null;
}
/// Save arbitrary data to the current save slot. This is only possible if a save has been loaded, and the data will be lost if the player exits without saving the current day.
/// The model type. This should be a plain class that has public properties for the data you want. The properties can be complex types.
/// The unique key identifying the data.
/// The arbitrary data to save.
/// The player hasn't loaded a save file yet or isn't the main player.
public void WriteSaveData(string key, TModel data) where TModel : class
{
if (!Context.IsSaveLoaded)
throw new InvalidOperationException($"Can't use {nameof(IMod.Helper)}.{nameof(IModHelper.Data)}.{nameof(this.WriteSaveData)} when a save file isn't loaded.");
if (!Context.IsMainPlayer)
throw new InvalidOperationException($"Can't use {nameof(IMod.Helper)}.{nameof(IModHelper.Data)}.{nameof(this.ReadSaveData)} because this isn't the main player. (Save files are stored on the main player's computer.)");
Game1.CustomData[this.GetSaveFileKey(key)] = this.JsonHelper.Serialise(data, Formatting.None);
}
/****
** Global app data
****/
/// Read arbitrary data stored on the local computer, synchronised by GOG/Steam if applicable.
/// The model type. This should be a plain class that has public properties for the data you want. The properties can be complex types.
/// The unique key identifying the data.
/// Returns the parsed data, or null if the entry doesn't exist or is empty.
public TModel ReadGlobalData(string key) where TModel : class
{
string path = this.GetGlobalDataPath(key);
return this.JsonHelper.ReadJsonFileIfExists(path, out TModel data)
? data
: null;
}
/// Save arbitrary data to the local computer, synchronised by GOG/Steam if applicable.
/// The model type. This should be a plain class that has public properties for the data you want. The properties can be complex types.
/// The unique key identifying the data.
/// The arbitrary data to save.
public void WriteGlobalData(string key, TModel data) where TModel : class
{
string path = this.GetGlobalDataPath(key);
this.JsonHelper.WriteJsonFile(path, data);
}
/*********
** Public methods
*********/
/// Get the unique key for a save file data entry.
/// The unique key identifying the data.
private string GetSaveFileKey(string key)
{
this.AssertSlug(key, nameof(key));
return $"smapi-mod-data/{this.ModID}/{key}".ToLower();
}
/// Get the absolute path for a global data file.
/// The unique key identifying the data.
private string GetGlobalDataPath(string key)
{
this.AssertSlug(key, nameof(key));
return Path.Combine(Constants.SavesPath, ".smapi-mod-data", this.ModID.ToLower(), $"{key}.json".ToLower());
}
/// Assert that a key contains only characters that are safe in all contexts.
/// The key to check.
/// The argument name for any assertion error.
private void AssertSlug(string key, string paramName)
{
if (!PathUtilities.IsSlug(key))
throw new ArgumentException("The data key is invalid (keys must only contain letters, numbers, underscores, periods, or hyphens).", paramName);
}
}
}