RegexBot/Common/EntityName.cs
Noi 1149f2800d Reorganized project
Moved modules into the assembly itself to simplify development of
further features and reduce complexity in building this project.

Additionally, many small adjustments were made, including:
- Add documentation to most public methods that had it missing
- Minor style updates
- Updated readme to reflect near-completion of this rewrite
- Remove any last remaining references to old project name Kerobot
- Update dependencies
2022-07-20 18:55:08 -07:00

179 lines
7.2 KiB
C#

namespace RegexBot.Common;
/// <summary>
/// Helper class that holds an entity's name, ID, or both.
/// Meant to be used during configuration processing in cases where the configuration expects
/// an entity name to be defined in a certain way which may or may not include its snowflake ID.
/// </summary>
public class EntityName {
/// <summary>
/// The entity's type, if specified in configuration.
/// </summary>
public EntityType Type { get; private set; }
/// <summary>
/// Entity's unique ID value (snowflake). May be null if the value is not known.
/// </summary>
public ulong? Id { get; private set; }
/// <summary>
/// Entity's name as specified in configuration. May be null if it was not specified.
/// This value is not updated during runtime.
/// </summary>
public string? Name { get; private set; }
// TODO elsewhere: find a way to emit a warning if the user specified a name without ID in configuration.
/// <summary>
/// Creates a new object instance from the given input string.
/// Documentation for the EntityName format can be found elsewhere in this project's documentation.
/// </summary>
/// <param name="input">Input string in EntityName format.</param>
/// <exception cref="ArgumentNullException">Input string is null or blank.</exception>
/// <exception cref="ArgumentException">Input string cannot be resolved to an entity type.</exception>
public EntityName(string input) {
if (string.IsNullOrWhiteSpace(input))
throw new ArgumentNullException(nameof(input), "Specified name is blank.");
// Check if type prefix was specified and extract it
Type = default;
if (input.Length >= 2) {
if (input[0] == '&') Type = EntityType.Role;
else if (input[0] == '#') Type = EntityType.Channel;
else if (input[0] == '@') Type = EntityType.User;
}
if (Type == default)
throw new ArgumentException("Entity type unable to be inferred by given input.");
input = input[1..]; // Remove prefix
// Input contains ID/Label separator?
var separator = input.IndexOf("::");
if (separator != -1) {
Name = input[(separator + 2)..];
if (ulong.TryParse(input.AsSpan(0, separator), out var parseOut)) {
// Got an ID.
Id = parseOut;
} else {
// It's not actually an ID. Assuming the entire string is a name.
Name = input;
Id = null;
}
} else {
// No separator. Input is either entirely an ID or entirely a Name.
if (ulong.TryParse(input, out var parseOut)) {
// ID without name.
Id = parseOut;
Name = null;
} else {
// Name without ID.
Name = input;
Id = null;
}
}
}
internal void SetId(ulong id) {
if (!Id.HasValue) Id = id;
}
/// <summary>
/// Returns the appropriate prefix corresponding to an EntityType.
/// </summary>
public static char Prefix(EntityType t) => t switch {
EntityType.Role => '&',
EntityType.Channel => '#',
EntityType.User => '@',
_ => '\0',
};
/// <summary>
/// Returns a string representation of this item in proper EntityName format.
/// </summary>
public override string ToString() {
var pf = Prefix(Type);
if (Id.HasValue && Name != null)
return $"{pf}{Id.Value}::{Name}";
else if (Id.HasValue)
return $"{pf}{Id}";
else
return $"{pf}{Name}";
}
#region Helper methods
/// <summary>
/// Attempts to find the corresponding role within the given guild.
/// </summary>
/// <param name="guild">The guild in which to search for the role.</param>
/// <param name="updateMissingID">
/// Specifies if this EntityName instance should cache the snowflake ID of the
/// corresponding role found in this guild if it is not already known by this instance.
/// </param>
public SocketRole? FindRoleIn(SocketGuild guild, bool updateMissingID = false) {
if (Type != EntityType.Role)
throw new ArgumentException("This EntityName instance must correspond to a Role.");
var dirty = false; // flag for updating ID if possible regardless of updateMissingId setting
if (Id.HasValue) {
var role = guild.GetRole(Id.Value);
if (role != null) return role;
else dirty = true; // only set if ID already existed but is now invalid
}
var r = guild.Roles.FirstOrDefault(rq => string.Equals(rq.Name, Name, StringComparison.OrdinalIgnoreCase));
if (r != null && (updateMissingID || dirty)) Id = r.Id;
return r;
}
/// <summary>
/// Attempts to find the corresponding user within the given guild.
/// </summary>
/// <param name="guild">The guild in which to search for the user.</param>
/// <param name="updateMissingID">
/// Specifies if this EntityName instance should cache the snowflake ID of the
/// corresponding user found in this guild if it is not already known by this instance.
/// </param>
public SocketGuildUser? FindUserIn(SocketGuild guild, bool updateMissingID = false) {
if (Type != EntityType.User)
throw new ArgumentException("This EntityName instance must correspond to a User.");
var dirty = false; // flag for updating ID if possible regardless of updateMissingId setting
if (Id.HasValue) {
var user = guild.GetUser(Id.Value);
if (user != null) return user;
else dirty = true; // only set if ID already existed but is now invalid
}
var u = guild.Users.FirstOrDefault(rq => string.Equals(rq.Username, Name, StringComparison.OrdinalIgnoreCase));
if (u != null && (updateMissingID || dirty)) Id = u.Id;
return u;
}
/// <summary>
/// Attempts to find the corresponding channel within the given guild.
/// </summary>
/// <param name="guild">The guild in which to search for the channel.</param>
/// <param name="updateMissingID">
/// Specifies if this EntityName instance should cache the snowflake ID of the
/// corresponding channel found in this guild if it is not already known by this instance.
/// </param>
public SocketTextChannel? FindChannelIn(SocketGuild guild, bool updateMissingID = false) {
if (Type != EntityType.Channel)
throw new ArgumentException("This EntityName instance must correspond to a Channel.");
var dirty = false; // flag for updating ID if possible regardless of updateMissingId setting
if (Id.HasValue) {
var channel = guild.GetTextChannel(Id.Value);
if (channel != null) return channel;
else dirty = true; // only set if ID already existed but is now invalid
}
var c = guild.TextChannels.FirstOrDefault(rq => string.Equals(rq.Name, Name, StringComparison.OrdinalIgnoreCase));
if (c != null && (updateMissingID || dirty)) Id = c.Id;
return c;
}
#endregion
}