using System;
using System.Collections.Generic;
using System.Linq;
namespace StardewModdingAPI.Framework
{
/// Manages deprecation warnings.
internal class DeprecationManager
{
/*********
** Properties
*********/
/// The deprecations which have already been logged (as 'mod name::noun phrase::version').
private readonly HashSet LoggedDeprecations = new HashSet(StringComparer.InvariantCultureIgnoreCase);
/// Encapsulates monitoring and logging for a given module.
private readonly IMonitor Monitor;
/// Tracks the installed mods.
private readonly ModRegistry ModRegistry;
/// The queued deprecation warnings to display.
private readonly IList QueuedWarnings = new List();
/*********
** Public methods
*********/
/// Construct an instance.
/// Encapsulates monitoring and logging for a given module.
/// Tracks the installed mods.
public DeprecationManager(IMonitor monitor, ModRegistry modRegistry)
{
this.Monitor = monitor;
this.ModRegistry = modRegistry;
}
/// Log a deprecation warning.
/// A noun phrase describing what is deprecated.
/// The SMAPI version which deprecated it.
/// How deprecated the code is.
public void Warn(string nounPhrase, string version, DeprecationLevel severity)
{
this.Warn(this.ModRegistry.GetFromStack()?.DisplayName, nounPhrase, version, severity);
}
/// Log a deprecation warning.
/// The friendly mod name which used the deprecated code.
/// A noun phrase describing what is deprecated.
/// The SMAPI version which deprecated it.
/// How deprecated the code is.
public void Warn(string source, string nounPhrase, string version, DeprecationLevel severity)
{
// ignore if already warned
if (!this.MarkWarned(source ?? "", nounPhrase, version))
return;
// queue warning
this.QueuedWarnings.Add(new DeprecationWarning(source, nounPhrase, version, severity));
}
/// Print any queued messages.
public void PrintQueued()
{
foreach (DeprecationWarning warning in this.QueuedWarnings.OrderBy(p => p.ModName).ThenBy(p => p.NounPhrase))
{
// build message
string message = $"{warning.ModName ?? "An unknown mod"} uses deprecated code ({warning.NounPhrase} is deprecated since SMAPI {warning.Version}).";
if (warning.ModName == null)
message += $"{Environment.NewLine}{Environment.StackTrace}";
// log message
switch (warning.Level)
{
case DeprecationLevel.Notice:
this.Monitor.Log(message, LogLevel.Trace);
break;
case DeprecationLevel.Info:
this.Monitor.Log(message, LogLevel.Debug);
break;
case DeprecationLevel.PendingRemoval:
this.Monitor.Log(message, LogLevel.Warn);
break;
default:
throw new NotSupportedException($"Unknown deprecation level '{warning.Level}'.");
}
}
this.QueuedWarnings.Clear();
}
/// Mark a deprecation warning as already logged.
/// A noun phrase describing what is deprecated (e.g. "the Extensions.AsInt32 method").
/// The SMAPI version which deprecated it.
/// Returns whether the deprecation was successfully marked as warned. Returns false if it was already marked.
public bool MarkWarned(string nounPhrase, string version)
{
return this.MarkWarned(this.ModRegistry.GetFromStack()?.DisplayName, nounPhrase, version);
}
/// Mark a deprecation warning as already logged.
/// The friendly name of the assembly which used the deprecated code.
/// A noun phrase describing what is deprecated (e.g. "the Extensions.AsInt32 method").
/// The SMAPI version which deprecated it.
/// Returns whether the deprecation was successfully marked as warned. Returns false if it was already marked.
public bool MarkWarned(string source, string nounPhrase, string version)
{
if (string.IsNullOrWhiteSpace(source))
throw new InvalidOperationException("The deprecation source cannot be empty.");
string key = $"{source}::{nounPhrase}::{version}";
if (this.LoggedDeprecations.Contains(key))
return false;
this.LoggedDeprecations.Add(key);
return true;
}
}
}