diff --git a/libcockatrice_card/libcockatrice/card/database/card_database.h b/libcockatrice_card/libcockatrice/card/database/card_database.h index 9fd240d46..4b2769fcb 100644 --- a/libcockatrice_card/libcockatrice/card/database/card_database.h +++ b/libcockatrice_card/libcockatrice/card/database/card_database.h @@ -1,7 +1,8 @@ /** * @file card_database.h * @ingroup CardDatabase - * @brief The CardDatabase is responsible for holding the card and set maps. + * @brief The CardDatabase is responsible for holding the card and set maps, managing card additions/removals, + * and providing access to sets and card querying via CardDatabaseQuerier. */ #ifndef CARDDATABASE_H @@ -24,85 +25,167 @@ inline Q_LOGGING_CATEGORY(CardDatabaseLog, "card_database"); +/** + * @class CardDatabase + * @ingroup CardDatabase + * @brief Core in-memory container for card and set data. + * + * Responsible for maintaining CardInfo objects, CardSet objects, and + * providing access to CardDatabaseQuerier for query operations. + * Handles addition, removal, and clearing of cards and sets. + */ class CardDatabase : public QObject { Q_OBJECT + protected: + /// Controller to determine set priority when choosing preferred printings. ICardSetPriorityController *setPriorityController; - /* - * The cards, indexed by name. - */ + /// Cards indexed by exact name CardNameMap cards; - /** - * The cards, indexed by their simple name. - */ + /// Cards indexed by simplified name (normalized) CardNameMap simpleNameCards; - /* - * The sets, indexed by short name. - */ + /// Sets indexed by short name SetNameMap sets; - // loader responsible for file discovery & parsing + /// Loader responsible for file discovery and parsing CardDatabaseLoader *loader; + /// Current load status of the database LoadStatus loadStatus; + /// Querier for higher-level card lookups CardDatabaseQuerier *querier; private: + /** + * @brief Check for sets that are unknown and emit signals if needed. + */ void checkUnknownSets(); + + /** + * @brief Refreshes the cached reverse-related cards for all cards. + */ void refreshCachedReverseRelatedCards(); + /// Mutexes for thread safety QBasicMutex *clearDatabaseMutex = new QBasicMutex(), *addCardMutex = new QBasicMutex(), *removeCardMutex = new QBasicMutex(); public: + /** + * @brief Constructs a new CardDatabase instance. + * @param parent QObject parent. + * @param prefs Optional card preference provider. + * @param pathProvider Optional database path provider. + * @param setPriorityController Optional controller for set priority. + */ explicit CardDatabase(QObject *parent = nullptr, ICardPreferenceProvider *prefs = nullptr, ICardDatabasePathProvider *pathProvider = nullptr, ICardSetPriorityController *setPriorityController = nullptr); + + /** @brief Destructor clears all internal data. */ ~CardDatabase() override; + /** + * @brief Removes a card from the database. + * @param card Pointer to the card to remove. + */ void removeCard(CardInfoPtr card); + + /** @brief Clears all cards, sets, and internal state. */ void clear(); + /** @brief Returns the map of cards by name. */ const CardNameMap &getCardList() const { return cards; } + + /** + * @brief Retrieves a set by short name, creating a new one if missing. + * @param setName Short name of the set. + * @return Pointer to the CardSet. + */ CardSetPtr getSet(const QString &setName); + + /** @brief Returns a list of all sets in the database. */ CardSetList getSetList() const; + + /** @brief Returns the current load status. */ LoadStatus getLoadStatus() const { return loadStatus; } + + /** @brief Returns the querier for performing card lookups. */ CardDatabaseQuerier *query() const { return querier; } + + /** @brief Enables all unknown sets in the database. */ void enableAllUnknownSets(); + + /** @brief Marks all sets as known. */ void markAllSetsAsKnown(); + + /** @brief Notifies listeners that enabled sets changed. */ void notifyEnabledSetsChanged(); public slots: + /** + * @brief Adds a card to the database. + * @param card CardInfoPtr to add. + */ void addCard(CardInfoPtr card); + + /** + * @brief Adds a set to the database. + * @param set Pointer to CardSet to add. + */ void addSet(CardSetPtr set); + + /** @brief Loads card databases from configured paths. */ void loadCardDatabases(); + + /** @brief Saves custom tokens to file. + * @return True if successful. + */ bool saveCustomTokensToFile(); + signals: + /** @brief Emitted when the card database has finished loading successfully. */ void cardDatabaseLoadingFinished(); + + /** @brief Emitted when the card database fails to load. */ void cardDatabaseLoadingFailed(); + + /** + * @brief Emitted when new sets are found. + * @param numUnknownSets Number of unknown sets. + * @param unknownSetsNames Names of unknown sets. + */ void cardDatabaseNewSetsFound(int numUnknownSets, QStringList unknownSetsNames); + + /** @brief Emitted when all new sets have been enabled. */ void cardDatabaseAllNewSetsEnabled(); + + /** @brief Emitted when enabled sets have changed. */ void cardDatabaseEnabledSetsChanged(); + + /** @brief Emitted when a new card is added. */ void cardAdded(CardInfoPtr card); + + /** @brief Emitted when a card is removed. */ void cardRemoved(CardInfoPtr card); friend class CardDatabaseLoader; friend class CardDatabaseQuerier; }; -#endif +#endif // CARDDATABASE_H diff --git a/libcockatrice_card/libcockatrice/card/database/card_database_loader.h b/libcockatrice_card/libcockatrice/card/database/card_database_loader.h index 0142b9fce..7bf02cc9a 100644 --- a/libcockatrice_card/libcockatrice/card/database/card_database_loader.h +++ b/libcockatrice_card/libcockatrice/card/database/card_database_loader.h @@ -1,7 +1,10 @@ /** * @file card_database_loader.h * @ingroup CardDatabase - * @brief The CardDatabaseLoader is responsible for populating the card database from files on disk. + * @brief The CardDatabaseLoader is responsible for discovering, loading, and saving card databases from files on disk. + * + * This class interacts with available parsers to populate a CardDatabase instance. It also handles + * loading main, token, spoiler, and custom card databases. */ #ifndef COCKATRICE_CARD_DATABASE_LOADER_H @@ -20,51 +23,111 @@ inline Q_LOGGING_CATEGORY(CardDatabaseLoadingSuccessOrFailureLog, "card_database class CardDatabase; class ICardDatabaseParser; +/** + * @enum LoadStatus + * @brief Represents the result of attempting to load a card database. + */ enum LoadStatus { - Ok, - VersionTooOld, - Invalid, - NotLoaded, - FileError, - NoCards + Ok, /**< Database loaded successfully. */ + VersionTooOld, /**< Database version is too old to load. */ + Invalid, /**< Database is invalid or unparsable. */ + NotLoaded, /**< Database has not been loaded. */ + FileError, /**< Error opening or reading the file. */ + NoCards /**< Database contains no cards. */ }; +/** + * @class CardDatabaseLoader + * @ingroup CardDatabase + * @brief Handles loading card databases from disk and saving custom tokens. + * + * This class is responsible for: + * - Discovering configured card database paths. + * - Loading main, token, spoiler, and custom databases. + * - Populating a CardDatabase instance using connected parsers. + * - Emitting signals about loading progress and new sets. + */ class CardDatabaseLoader : public QObject { Q_OBJECT public: + /** + * @brief Constructs a CardDatabaseLoader. + * @param parent QObject parent. + * @param db Pointer to the CardDatabase to populate (non-owning). + * @param pathProvider Provider for card database file paths. + * @param preferenceProvider Optional card preference provider for pinned printings. + */ explicit CardDatabaseLoader(QObject *parent, CardDatabase *db, ICardDatabasePathProvider *pathProvider, ICardPreferenceProvider *preferenceProvider); + + /** @brief Destructor cleans up allocated parsers. */ ~CardDatabaseLoader() override; public slots: - LoadStatus loadCardDatabases(); // discover & load the configured databases - LoadStatus loadCardDatabase(const QString &path); // load a single file - bool saveCustomTokensToFile(); // write tokens to custom DB path + /** + * @brief Loads all configured card databases. + * @return Status of the main database load. + */ + LoadStatus loadCardDatabases(); + + /** + * @brief Loads a single card database file. + * @param path Path to the database file. + * @return LoadStatus indicating success or failure. + */ + LoadStatus loadCardDatabase(const QString &path); + + /** + * @brief Saves custom tokens to the user-defined custom database path. + * @return True if the save was successful. + */ + bool saveCustomTokensToFile(); signals: + /** @brief Emitted when loading starts. */ void loadingStarted(); + + /** @brief Emitted when loading finishes successfully. */ void loadingFinished(); + + /** @brief Emitted when loading fails. */ void loadingFailed(); + + /** + * @brief Emitted when new sets are discovered during loading. + * @param numSets Number of new sets. + * @param setNames Names of the discovered sets. + */ void newSetsFound(int numSets, const QStringList &setNames); + + /** @brief Emitted when all newly discovered sets have been enabled. */ void allNewSetsEnabled(); private: - LoadStatus loadFromFile(const QString &fileName); // internal helper + /** + * @brief Loads a database from a single file using the available parsers. + * @param fileName Path to the database file. + * @return LoadStatus indicating success or failure. + */ + LoadStatus loadFromFile(const QString &fileName); + + /** + * @brief Collects custom card database paths recursively. + * @return Sorted list of file paths to custom databases. + */ QStringList collectCustomDatabasePaths() const; - CardDatabase *database; // non-owning pointer to the container +private: + CardDatabase *database; /**< Non-owning pointer to the target CardDatabase. */ + ICardDatabasePathProvider *pathProvider; /**< Pointer to the path provider. */ + QList availableParsers; /**< List of available parsers for different formats. */ - ICardDatabasePathProvider *pathProvider; // pointer to the implementation providing the paths - - // parsers - QList availableParsers; - - QBasicMutex *loadFromFileMutex = new QBasicMutex(); - QBasicMutex *reloadDatabaseMutex = new QBasicMutex(); + QBasicMutex *loadFromFileMutex = new QBasicMutex(); /**< Mutex for single-file loading. */ + QBasicMutex *reloadDatabaseMutex = new QBasicMutex(); /**< Mutex for reloading entire database. */ }; #endif // COCKATRICE_CARD_DATABASE_LOADER_H diff --git a/libcockatrice_card/libcockatrice/card/database/card_database_manager.h b/libcockatrice_card/libcockatrice/card/database/card_database_manager.h index 58503d2ff..58a744fbb 100644 --- a/libcockatrice_card/libcockatrice/card/database/card_database_manager.h +++ b/libcockatrice_card/libcockatrice/card/database/card_database_manager.h @@ -1,36 +1,79 @@ -/** - * @file card_database_manager.h - * @ingroup CardDatabase - * @brief The CardDatabaseManager is responsible for managing the global database singleton. - */ - #ifndef CARD_DATABASE_ACCESSOR_H #define CARD_DATABASE_ACCESSOR_H #pragma once #include "card_database.h" +/** + * @class CardDatabaseManager + * @ingroup CardDatabase + * @brief The CardDatabaseManager is responsible for managing the global CardDatabase singleton. + * + * This class provides a static interface for accessing the global CardDatabase instance + * and its CardDatabaseQuerier. It also allows the configuration of optional providers: + * - ICardPreferenceProvider + * - ICardDatabasePathProvider + * - ICardSetPriorityController + * + * Only a single instance of CardDatabase exists, enforced via a private constructor and + * deleted copy/move operations. + */ class CardDatabaseManager { public: - // Delete copy constructor and assignment operator to enforce singleton + /** @brief Deleted copy constructor to enforce singleton. */ CardDatabaseManager(const CardDatabaseManager &) = delete; + + /** @brief Deleted assignment operator to enforce singleton. */ CardDatabaseManager &operator=(const CardDatabaseManager &) = delete; - // To be called once, before instantiation of the manager + /** + * @brief Sets the card preference provider. + * @param provider Pointer to an ICardPreferenceProvider. + * @note Must be called before the first call to getInstance(). + */ static void setCardPreferenceProvider(ICardPreferenceProvider *provider); + + /** + * @brief Sets the card database path provider. + * @param provider Pointer to an ICardDatabasePathProvider. + * @note Must be called before the first call to getInstance(). + */ static void setCardDatabasePathProvider(ICardDatabasePathProvider *provider); + + /** + * @brief Sets the card set priority controller. + * @param controller Pointer to an ICardSetPriorityController. + * @note Must be called before the first call to getInstance(). + */ static void setCardSetPriorityController(ICardSetPriorityController *controller); - // Static method to access the singleton instance + /** + * @brief Returns the singleton CardDatabase instance. + * @return Pointer to the global CardDatabase. + */ static CardDatabase *getInstance(); + + /** + * @brief Returns the CardDatabaseQuerier of the singleton database. + * @return Pointer to CardDatabaseQuerier. + */ static CardDatabaseQuerier *query(); private: - CardDatabaseManager() = default; // Private constructor + /** @brief Private default constructor to enforce singleton. */ + CardDatabaseManager() = default; + + /** @brief Private destructor. */ ~CardDatabaseManager() = default; + + /// Static card preference provider pointer (default: Noop) static ICardPreferenceProvider *cardPreferenceProvider; + + /// Static path provider pointer (default: Noop) static ICardDatabasePathProvider *pathProvider; + + /// Static set priority controller pointer (default: Noop) static ICardSetPriorityController *setPriorityController; }; diff --git a/libcockatrice_card/libcockatrice/card/database/card_database_querier.h b/libcockatrice_card/libcockatrice/card/database/card_database_querier.h index 052ed5c7f..fcef3fea1 100644 --- a/libcockatrice_card/libcockatrice/card/database/card_database_querier.h +++ b/libcockatrice_card/libcockatrice/card/database/card_database_querier.h @@ -1,9 +1,3 @@ -/** - * @file card_database_querier.h - * @ingroup CardDatabase - * @brief The CardDatabaseQuerier is responsible for querying the database and returning data. - */ - #ifndef COCKATRICE_CARD_DATABASE_QUERIER_H #define COCKATRICE_CARD_DATABASE_QUERIER_H @@ -15,51 +9,215 @@ #include class CardDatabase; + +/** + * @class CardDatabaseQuerier + * @ingroup CardDatabase + * @brief Provides lookup and convenience functions for querying cards and their printings. + * + * The CardDatabaseQuerier class offers various lookup helpers for retrieving card information + * (e.g., CardInfoPtr, ExactCard, and PrintingInfo) from a CardDatabase. It also applies user + * printing preferences via ICardPreferenceProvider when determining preferred printings. + */ class CardDatabaseQuerier : public QObject { Q_OBJECT public: + /** + * @brief Constructs a CardDatabaseQuerier. + * + * @param parent Parent QObject. + * @param db Pointer to the CardDatabase used for lookups. + * @param prefs Pointer to card preference provider which supplies user-preference for printings. + */ explicit CardDatabaseQuerier(QObject *parent, const CardDatabase *db, const ICardPreferenceProvider *prefs); + /** + * @brief Retrieves a card by its exact name. + * + * @param cardName Exact card name. + * @return A CardInfoPtr, or null if no matching card exists. + */ [[nodiscard]] CardInfoPtr getCardInfo(const QString &cardName) const; + + /** + * @brief Retrieves multiple cards by their exact names. + * + * Failed lookups are skipped and not included in the result. + * + * @param cardNames List of exact card names. + * @return List of CardInfoPtr objects for which a match was found. + */ [[nodiscard]] QList getCardInfos(const QStringList &cardNames) const; - /* - * Get a card by its simple name. The name will be simplified in this - * function, so you don't need to simplify it beforehand. + /** + * @brief Retrieves a card using simplified name matching. + * + * The name is automatically normalized, so callers do not need to simplify it. + * + * @param cardName A (possibly simplified or misspelled) card name. + * @return A CardInfoPtr, or null if not found. */ [[nodiscard]] CardInfoPtr getCardBySimpleName(const QString &cardName) const; - [[nodiscard]] ExactCard guessCard(const CardRef &cardRef) const; + /** + * @brief Looks up a card using exact name first, then simplified matching as fallback. + * + * @param name Raw card name input. + * @return The best-match CardInfoPtr, or null if no match is found. + */ + [[nodiscard]] CardInfoPtr lookupCardByName(const QString &name) const; + + /** + * @brief Converts a CardRef into an ExactCard. + * + * If the providerId is empty, the preferred printing is used. + * If providerId exists but cannot be found, an ExactCard with an empty PrintingInfo is returned. + * + * @param cardRef Card reference with name and optional providerId. + * @return The resolved ExactCard, or empty if no card was found. + */ [[nodiscard]] ExactCard getCard(const CardRef &cardRef) const; + + /** + * @brief Resolves multiple CardRefs into ExactCards. + * + * Failed entries are not included in the result. + * + * @param cardRefs List of card references. + * @return List of successfully resolved ExactCards. + */ [[nodiscard]] QList getCards(const QList &cardRefs) const; + /** + * @brief Attempts a more flexible card lookup using both simple name matching and CardRef rules. + * + * If providerId is missing, uses preferred printing. If lookup fails, attempts simplified name. + * + * @param cardRef Card reference to resolve. + * @return The best-guess ExactCard, or empty if unresolved. + */ + [[nodiscard]] ExactCard guessCard(const CardRef &cardRef) const; + + /** + * @brief Returns a random card from the database using the preferred printing. + * + * @return A random ExactCard, or empty if the database is empty. + */ [[nodiscard]] ExactCard getRandomCard() const; + + /** + * @brief Returns a printing of a card from the same set as another given printing when possible. + * + * If no matching printing exists, falls back to a standard lookup. + * + * @param cardName Card to retrieve. + * @param otherPrinting Printing to match the set against. + * @return Matching ExactCard if found, otherwise fallback ExactCard. + */ [[nodiscard]] ExactCard getCardFromSameSet(const QString &cardName, const PrintingInfo &otherPrinting) const; - [[nodiscard]] ExactCard getPreferredCard(const CardInfoPtr &card) const; + /** + * @brief Returns the preferred printing of a card based on user preferences and set priority. + * + * @param cardName Name of the card. + * @return The preferred ExactCard. + */ + ExactCard getPreferredCard(const QString &cardName) const; + + /** + * @brief Returns the preferred printing of a card based on user preferences and set priority. + * + * @param cardInfo Card information object. + * @return The preferred ExactCard. + */ + [[nodiscard]] ExactCard getPreferredCard(const CardInfoPtr &cardInfo) const; + + /** + * @brief Checks whether the CardRef refers to the preferred printing. + * + * @param cardRef Card reference to test. + * @return True if providerId matches the preferred printing. + */ [[nodiscard]] bool isPreferredPrinting(const CardRef &cardRef) const; - [[nodiscard]] PrintingInfo getPreferredPrinting(const CardInfoPtr &card) const; + + /** + * @brief Returns the preferred printing for the given card name. + * + * @param cardName Card name. + * @return Preferred PrintingInfo, or empty if not found. + */ [[nodiscard]] PrintingInfo getPreferredPrinting(const QString &cardName) const; + + /** + * @brief Returns the preferred printing for the given card. + * + * @param cardInfo Card information object. + * @return Preferred PrintingInfo, or empty if not applicable. + */ + [[nodiscard]] PrintingInfo getPreferredPrinting(const CardInfoPtr &cardInfo) const; + + /** + * @brief Returns the providerId of the preferred printing. + * + * @param cardName Card name. + * @return ProviderId string for preferred printing. + */ [[nodiscard]] QString getPreferredPrintingProviderId(const QString &cardName) const; + /** + * @brief Retrieves a specific printing referenced by CardRef. + * + * @param cardRef Card reference including providerId. + * @return Matching PrintingInfo, or empty if not found. + */ [[nodiscard]] PrintingInfo getSpecificPrinting(const CardRef &cardRef) const; + + /** + * @brief Searches for a specific printing by set code and collector number. + * + * @param cardName Card name to search. + * @param setCode Set (short) code to match. + * @param collectorNumber Collector number. If empty, any printing from the set is returned. + * @return Matching PrintingInfo, or empty if not found. + */ [[nodiscard]] PrintingInfo getSpecificPrinting(const QString &cardName, const QString &setCode, const QString &collectorNumber) const; - ExactCard getPreferredCard(const QString &cardName) const; + + /** + * @brief Searches for a printing that matches a given providerId. + * + * @param card Card to search. + * @param providerId Provider identifier to match. + * @return Matching PrintingInfo, or empty if not found. + */ [[nodiscard]] PrintingInfo findPrintingWithId(const CardInfoPtr &card, const QString &providerId) const; + /** + * @brief Returns a list of all main card types present in the database. + * + * @return List of main card type strings. + */ [[nodiscard]] QStringList getAllMainCardTypes() const; + + /** + * @brief Returns a mapping of main card types to their occurrence counts. + * + * @return Map of main card type to count. + */ [[nodiscard]] QMap getAllMainCardTypesWithCount() const; + + /** + * @brief Returns a mapping of card subtypes to their occurrence counts. + * + * @return Map of subtype string to count. + */ [[nodiscard]] QMap getAllSubCardTypesWithCount() const; private: - const CardDatabase *db; - - const ICardPreferenceProvider *prefs; - - CardInfoPtr lookupCardByName(const QString &name) const; + const CardDatabase *db; //!< Card database used for all lookups. + const ICardPreferenceProvider *prefs; //!< Preference provider for preferred printings. }; #endif // COCKATRICE_CARD_DATABASE_QUERIER_H diff --git a/libcockatrice_card/libcockatrice/card/database/parser/card_database_parser.h b/libcockatrice_card/libcockatrice/card/database/parser/card_database_parser.h index c67e3dafe..35012dbc5 100644 --- a/libcockatrice_card/libcockatrice/card/database/parser/card_database_parser.h +++ b/libcockatrice_card/libcockatrice/card/database/parser/card_database_parser.h @@ -1,9 +1,3 @@ -/** - * @file card_database_parser.h - * @ingroup CardDatabaseParsers - * @brief The ICardDatabaseParser defines the base interface for parser sub-classes. - */ - #ifndef CARDDATABASE_PARSER_H #define CARDDATABASE_PARSER_H @@ -14,35 +8,76 @@ #define COCKATRICE_XML_XSI_NAMESPACE "http://www.w3.org/2001/XMLSchema-instance" +/** + * @class ICardDatabaseParser + * @ingroup CardDatabase + * @brief Defines the base parser interface (ICardDatabaseParser) for all card database parsers. + * + * Provides methods for checking file compatibility, parsing, and saving card databases. + * Also provides shared access to the global set list for cross-referencing. + */ class ICardDatabaseParser : public QObject { Q_OBJECT public: ~ICardDatabaseParser() override = default; + /** + * @brief Checks whether this parser can parse the given file. + * @param name File name (used for extension checks). + * @param device QIODevice representing the file content. + * @return true if the parser can handle this file. + */ virtual bool getCanParseFile(const QString &name, QIODevice &device) = 0; + + /** + * @brief Parses a database file and emits addCard/addSet signals. + * @param device QIODevice representing the file content. + */ virtual void parseFile(QIODevice &device) = 0; + + /** + * @brief Saves card and set data to a file. + * @param sets Map of sets to save. + * @param cards Map of cards to save. + * @param fileName Target file path. + * @param sourceUrl Optional source URL of the database. + * @param sourceVersion Optional version string of the source. + * @return true if save succeeded. + */ virtual bool saveToFile(SetNameMap sets, CardNameMap cards, const QString &fileName, const QString &sourceUrl = "unknown", const QString &sourceVersion = "unknown") = 0; + + /** @brief Clears the cached global set list. */ static void clearSetlist(); protected: - /* - * A cached list of the available sets, needed to cross-reference sets from cards. - * Shared between all parsers - */ + /** @brief Cached global list of sets shared between all parsers. */ static SetNameMap sets; + /** + * @brief Internal helper to add a set to the global set cache. + * @param setName Short set name. + * @param longName Optional full name. + * @param setType Optional set type string. + * @param releaseDate Optional release date. + * @param priority Optional priority (fallback if not specified). + * @return Pointer to the added or existing CardSet instance. + */ CardSetPtr internalAddSet(const QString &setName, const QString &longName = "", const QString &setType = "", const QDate &releaseDate = QDate(), const CardSet::Priority priority = CardSet::PriorityFallback); + signals: + /** Emitted when a card is loaded from the database. */ void addCard(CardInfoPtr card); + + /** Emitted when a set is loaded from the database. */ void addSet(CardSetPtr set); }; diff --git a/libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_3.h b/libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_3.h index 50fa9c587..a727561ea 100644 --- a/libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_3.h +++ b/libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_3.h @@ -1,9 +1,3 @@ -/** - * @file cockatrice_xml_3.h - * @ingroup CardDatabaseParsers - * @brief The CockatriceXml3Parser is capable of parsing version 3 of the Cockatrice XML Schema. - */ - #ifndef COCKATRICE_XML3_H #define COCKATRICE_XML3_H @@ -14,14 +8,44 @@ inline Q_LOGGING_CATEGORY(CockatriceXml3Log, "cockatrice_xml.xml_3_parser"); +/** + * @class CockatriceXml3Parser + * @ingroup CardDatabase + * @brief Parses version 3 of the Cockatrice XML Schema. + * + * This parser reads a Cockatrice XML3 database and emits CardInfoPtr + * and CardSetPtr objects. All card properties are read individually. + * + * @note Differences from v4: + * - No block; properties are hardcoded (manacost, cmc, type, pt, loyalty, etc.). + * - No set priority field. + * - No support for rebalanced cards or preferences. + * - Related cards support only attach, exclude, variable, and count attributes. + */ class CockatriceXml3Parser : public ICardDatabaseParser { Q_OBJECT public: CockatriceXml3Parser() = default; ~CockatriceXml3Parser() override = default; + + /** + * @brief Determines if the parser can handle this file. + * @param name File name. + * @param device Open QIODevice containing the XML. + * @return True if the file is a Cockatrice XML3 database. + */ bool getCanParseFile(const QString &name, QIODevice &device) override; + + /** + * @brief Parse the XML database. + * @param device Open QIODevice positioned at start of file. + */ void parseFile(QIODevice &device) override; + + /** + * @brief Save sets and cards back to an XML3 file. + */ bool saveToFile(SetNameMap _sets, CardNameMap cards, const QString &fileName, @@ -29,8 +53,25 @@ public: const QString &sourceVersion = "unknown") override; private: + /** + * @brief Load all elements from the XML stream. + * @param xml The open QXmlStreamReader positioned at the element. + * Parses each node and emits addCard signals for each CardInfoPtr created. + */ void loadCardsFromXml(QXmlStreamReader &xml); + + /** + * @brief Load all elements from the XML stream. + * @param xml The open QXmlStreamReader positioned at the element. + * Parses each node and adds them to the shared set cache. + */ void loadSetsFromXml(QXmlStreamReader &xml); + + /** + * @brief Extracts the main card type from a full type string. + * @param type The full type string (e.g., "Legendary Artifact Creature - Golem") + * @return The primary type (e.g., "Creature"). + */ QString getMainCardType(QString &type); }; diff --git a/libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_4.h b/libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_4.h index 40badbf49..b83f6929e 100644 --- a/libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_4.h +++ b/libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_4.h @@ -1,9 +1,3 @@ -/** - * @file cockatrice_xml_4.h - * @ingroup CardDatabaseParsers - * @brief The CockatriceXml4Parser is capable of parsing version 4 of the Cockatrice XML Schema. - */ - #ifndef COCKATRICE_XML4_H #define COCKATRICE_XML4_H @@ -15,14 +9,46 @@ inline Q_LOGGING_CATEGORY(CockatriceXml4Log, "cockatrice_xml.xml_4_parser"); +/** + * @class CockatriceXml4Parser + * @ingroup CardDatabase + * @brief Parses version 4 of the Cockatrice XML Schema. + * + * This parser reads a Cockatrice XML4 database and emits CardInfoPtr + * and CardSetPtr objects. Card properties are read inside blocks, + * making the parser more extensible and schema-compliant. + * + * @note Differences from v3: + * - Card properties are stored in blocks as a QVariantHash. + * - Sets can include a element. + * - Supports user preferences via ICardPreferenceProvider (e.g., skipping rebalanced cards). + * - Related cards support persistent relations and multiple attach types (e.g., transform). + * - More robust serialization; easier to extend schema in the future. + */ class CockatriceXml4Parser : public ICardDatabaseParser { Q_OBJECT public: - CockatriceXml4Parser(ICardPreferenceProvider *cardPreferenceProvider); + explicit CockatriceXml4Parser(ICardPreferenceProvider *cardPreferenceProvider); ~CockatriceXml4Parser() override = default; + + /** + * @brief Determines if the parser can handle this file. + * @param name File name. + * @param device Open QIODevice containing the XML. + * @return True if the file is a Cockatrice XML4 database. + */ bool getCanParseFile(const QString &name, QIODevice &device) override; + + /** + * @brief Parse the XML database. + * @param device Open QIODevice positioned at start of file. + */ void parseFile(QIODevice &device) override; + + /** + * @brief Save sets and cards back to an XML4 file. + */ bool saveToFile(SetNameMap _sets, CardNameMap cards, const QString &fileName, @@ -30,10 +56,27 @@ public: const QString &sourceVersion = "unknown") override; private: - ICardPreferenceProvider *cardPreferenceProvider; + ICardPreferenceProvider *cardPreferenceProvider; ///< Interface to handle user preferences + /** + * @brief Loads a generic block from a element. + * @param xml The open QXmlStreamReader positioned at a element. + * @return A QVariantHash mapping property names to values. + */ QVariantHash loadCardPropertiesFromXml(QXmlStreamReader &xml); + + /** + * @brief Load all elements from the XML stream. + * @param xml The open QXmlStreamReader positioned at the element. + * Honors the user's preference regarding rebalanced cards. + */ void loadCardsFromXml(QXmlStreamReader &xml); + + /** + * @brief Load all elements from the XML stream. + * @param xml The open QXmlStreamReader positioned at the element. + * Parses nodes including priority information. + */ void loadSetsFromXml(QXmlStreamReader &xml); };