AnkiDeck.cs

using System.Collections.ObjectModel;
using System.Globalization;
using System.Text.Json;
 
namespace AnkiIO;

public sealed class AnkiDeck
{
    private readonly List<AnkiDeck> subdecks = [];
    private readonly List<AnkiNote> notes = [];
    private readonly ReadOnlyCollection<AnkiDeck> subdecksView;
    private readonly ReadOnlyCollection<AnkiNote> notesView;
    private ConventionalNoteTypeCache conventionalNoteTypes;

    public AnkiDeck(string name, long? id = null)
        : this(name, id, new ConventionalNoteTypeCache())
    {
    }
 
    private AnkiDeck(string name, long? id, ConventionalNoteTypeCache conventionalNoteTypes)
    {
        ArgumentException.ThrowIfNullOrWhiteSpace(name);
        if (name.Contains("::", StringComparison.Ordinal))
        {
            throw new ArgumentException("A deck segment cannot contain '::'. Build hierarchy with AddSubdeck().", nameof(name));
        }
 
        Name = name;
        Id = id ?? AnkiId.New();
        Media = new AnkiMediaCollection();
        subdecksView = subdecks.AsReadOnly();
        notesView = notes.AsReadOnly();
        this.conventionalNoteTypes = conventionalNoteTypes;
    }

    public long Id { get; }

    public string Name { get; }

    public string Description { get; set; } = string.Empty;

    public IDictionary<string, string> Metadata { get; } = new Dictionary<string, string>(StringComparer.Ordinal);

    public IDictionary<string, JsonElement> UnknownData { get; } = new Dictionary<string, JsonElement>(StringComparer.Ordinal);

    public AnkiMediaCollection Media { get; }

    public IReadOnlyList<AnkiDeck> Subdecks => subdecksView;

    public IReadOnlyList<AnkiNote> Notes => notesView;

    public AnkiDeck AddSubdeck(string name, long? id = null)
    {
        if (subdecks.Any(deck => string.Equals(deck.Name, name, StringComparison.OrdinalIgnoreCase)))
        {
            throw new ArgumentException($"Subdeck '{name}' already exists.", nameof(name));
        }
 
        var deck = new AnkiDeck(name, id, conventionalNoteTypes);
        subdecks.Add(deck);
        return deck;
    }

    public AnkiNote AddNote(AnkiNoteType noteType, IReadOnlyDictionary<string, string> fields, IEnumerable<string>? tags = null, string? guid = null, long? id = null)
    {
        ArgumentNullException.ThrowIfNull(noteType);
        ArgumentNullException.ThrowIfNull(fields);
        var note = new AnkiNote(noteType, fields, tags, id, guid);
        note.GenerateCards(Id, nameof(fields));
        notes.Add(note);
        conventionalNoteTypes.Observe(noteType);
        return note;
    }

    public bool RemoveNote(AnkiNote note) => notes.Remove(note);
 
    internal void AddExistingSubdeck(AnkiDeck deck)
    {
        deck.UseConventionalNoteTypes(conventionalNoteTypes);
        subdecks.Add(deck);
    }
 
    internal void AddExistingNote(AnkiNote note)
    {
        note.AttachToDeck(Id);
        notes.Add(note);
        conventionalNoteTypes.Observe(note.NoteType);
    }
 
    private void UseConventionalNoteTypes(ConventionalNoteTypeCache cache)
    {
        conventionalNoteTypes.CopyMissingTo(cache);
        conventionalNoteTypes = cache;
        foreach (var note in notes)
        {
            cache.Observe(note.NoteType);
        }
 
        foreach (var subdeck in subdecks)
        {
            subdeck.UseConventionalNoteTypes(cache);
        }
    }

    public IEnumerable<AnkiDeck> Traverse()
    {
        yield return this;
        foreach (var child in subdecks)
        {
            foreach (var descendant in child.Traverse())
            {
                yield return descendant;
            }
        }
    }

    public AnkiNote AddBasicNote(
        string front,
        string back,
        IEnumerable<string>? tags = null,
        string? guid = null,
        long? id = null)
    {
        ArgumentNullException.ThrowIfNull(front);
        ArgumentNullException.ThrowIfNull(back);
 
        return AddNote(
            conventionalNoteTypes.Basic ??= AnkiNoteTypes.CreateBasic(),
            new Dictionary<string, string>(StringComparer.Ordinal)
            {
                ["Front"] = front,
                ["Back"] = back,
            },
            tags,
            guid,
            id);
    }

    public AnkiNote AddBasicAndReversedNote(
        string front,
        string back,
        IEnumerable<string>? tags = null,
        string? guid = null,
        long? id = null)
    {
        ArgumentNullException.ThrowIfNull(front);
        ArgumentNullException.ThrowIfNull(back);
 
        return AddNote(
            conventionalNoteTypes.BasicAndReversed ??= AnkiNoteTypes.CreateBasicAndReversed(),
            new Dictionary<string, string>(StringComparer.Ordinal)
            {
                ["Front"] = front,
                ["Back"] = back,
            },
            tags,
            guid,
            id);
    }

    public AnkiNote AddClozeNote(
        string text,
        string extra = "",
        IEnumerable<string>? tags = null,
        string? guid = null,
        long? id = null)
    {
        ArgumentNullException.ThrowIfNull(text);
        ArgumentNullException.ThrowIfNull(extra);
        ValidateSimpleClozeText(text);
 
        return AddNote(
            conventionalNoteTypes.Cloze ??= AnkiNoteTypes.CreateCloze(),
            new Dictionary<string, string>(StringComparer.Ordinal)
            {
                ["Text"] = text,
                ["Extra"] = extra,
            },
            tags,
            guid,
            id);
    }
 
    private static void ValidateSimpleClozeText(string text)
    {
        const string marker = "{{c";
        var searchIndex = 0;
        var foundDeletion = false;
 
        while (text.IndexOf(marker, searchIndex, StringComparison.Ordinal) is var markerIndex && markerIndex >= 0)
        {
            var indexStart = markerIndex + marker.Length;
            if (indexStart >= text.Length || text[indexStart] is < '0' or > '9')
            {
                throw new ArgumentException(
                    "Cloze markers must place a positive numeric index after '{{c', such as '{{c1::answer}}'.",
                    nameof(text));
            }
 
            var contentSeparator = indexStart;
            while (contentSeparator < text.Length && text[contentSeparator] is >= '0' and <= '9')
            {
                contentSeparator++;
            }
 
            if (contentSeparator + 1 >= text.Length
                || text[contentSeparator] != ':'
                || text[contentSeparator + 1] != ':')
            {
                throw new ArgumentException("Cloze indexes must be followed by the '::' content separator.", nameof(text));
            }
 
            var indexText = text.AsSpan(indexStart, contentSeparator - indexStart);
            if (indexText[0] == '0'
                || !int.TryParse(indexText, NumberStyles.None, CultureInfo.InvariantCulture, out var index)
                || index < 1)
            {
                throw new ArgumentException("Cloze indexes must be positive integers representable by System.Int32.", nameof(text));
            }
 
            var contentStart = contentSeparator + 2;
            var closingDelimiter = text.IndexOf("}}", contentStart, StringComparison.Ordinal);
            if (closingDelimiter < 0)
            {
                throw new ArgumentException("Cloze deletions must end with '}}'.", nameof(text));
            }
 
            var content = text[contentStart..closingDelimiter];
            if (content.Contains("{{", StringComparison.Ordinal))
            {
                throw new ArgumentException("Nested cloze or template markup requires the low-level AddNote API.", nameof(text));
            }
 
            var hintSeparator = content.IndexOf("::", StringComparison.Ordinal);
            var answer = hintSeparator < 0 ? content : content[..hintSeparator];
            if (answer.Length == 0)
            {
                throw new ArgumentException("Cloze answer text cannot be empty.", nameof(text));
            }
 
            if (hintSeparator >= 0
                && content.IndexOf("::", hintSeparator + 2, StringComparison.Ordinal) >= 0)
            {
                throw new ArgumentException("Simple cloze markup can contain at most one hint separator.", nameof(text));
            }
 
            foundDeletion = true;
            searchIndex = closingDelimiter + 2;
        }
 
        if (!foundDeletion)
        {
            throw new ArgumentException("Cloze text must contain at least one positive deletion such as '{{c1::answer}}'.", nameof(text));
        }
    }
 
}