gitea-mirror/Cockatrice
1
0
Fork 0
mirror of https://github.com/Cockatrice/Cockatrice.git synced 2025-12-12 15:49:28 -08:00
Code Issues Packages Projects Releases Wiki Activity

[Doxygen] Card Database and related (#6303)

Browse Source 
Took 29 minutes


Took 24 seconds

Co-authored-by: Lukas Brübach <Bruebach.Lukas@bdosecurity.de>
This commit is contained in:
BruebachL
2025-11-11 06:46:08 +01:00
committed by GitHub
parent f00d415dd7
commit e9a9475ed7
7 changed files with 549 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

107
libcockatrice_card/libcockatrice/card/database/card_database.h
View File

@@ -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

101
libcockatrice_card/libcockatrice/card/database/card_database_loader.h
View File

@@ -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<ICardDatabaseParser *> availableParsers; /**< List of available parsers for different formats. */
ICardDatabasePathProvider *pathProvider; // pointer to the implementation providing the paths
// parsers
QList<ICardDatabaseParser *> 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

63
libcockatrice_card/libcockatrice/card/database/card_database_manager.h
View File

@@ -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;
};

194
libcockatrice_card/libcockatrice/card/database/card_database_querier.h
View File

@@ -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 <libcockatrice/utility/card_ref.h>
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<CardInfoPtr> 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<ExactCard> getCards(const QList<CardRef> &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<QString, int> getAllMainCardTypesWithCount() const;
/**
* @brief Returns a mapping of card subtypes to their occurrence counts.
*
* @return Map of subtype string to count.
*/
[[nodiscard]] QMap<QString, int> 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

55
libcockatrice_card/libcockatrice/card/database/parser/card_database_parser.h
View File

@@ -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);
};

53
libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_3.h
View File

@@ -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 <prop> 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 <card> elements from the XML stream.
* @param xml The open QXmlStreamReader positioned at the <cards> element.
* Parses each <card> node and emits addCard signals for each CardInfoPtr created.
*/
void loadCardsFromXml(QXmlStreamReader &xml);
/**
* @brief Load all <set> elements from the XML stream.
* @param xml The open QXmlStreamReader positioned at the <sets> element.
* Parses each <set> 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);
};

59
libcockatrice_card/libcockatrice/card/database/parser/cockatrice_xml_4.h
View File

@@ -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 <prop> blocks,
* making the parser more extensible and schema-compliant.
*
* @note Differences from v3:
* - Card properties are stored in <prop> blocks as a QVariantHash.
* - Sets can include a <priority> 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 <prop> block from a <card> element.
* @param xml The open QXmlStreamReader positioned at a <prop> element.
* @return A QVariantHash mapping property names to values.
*/
QVariantHash loadCardPropertiesFromXml(QXmlStreamReader &xml);
/**
* @brief Load all <card> elements from the XML stream.
* @param xml The open QXmlStreamReader positioned at the <cards> element.
* Honors the user's preference regarding rebalanced cards.
*/
void loadCardsFromXml(QXmlStreamReader &xml);
/**
* @brief Load all <set> elements from the XML stream.
* @param xml The open QXmlStreamReader positioned at the <sets> element.
* Parses <set> nodes including priority information.
*/
void loadSetsFromXml(QXmlStreamReader &xml);
};