From a167c3e2222b969a4aa65801ee1c0bc891928bea Mon Sep 17 00:00:00 2001 From: lonkaars Date: Sun, 25 Dec 2022 21:48:08 +0100 Subject: small refactoring and add documentation --- oop2eindopdr/CacheManager.cpp | 1 - oop2eindopdr/CacheManager.h | 8 +++++++- oop2eindopdr/DownloadManager.h | 3 +++ oop2eindopdr/Pokedex.h | 7 ++++++- oop2eindopdr/PokemonCard.h | 8 ++++++++ oop2eindopdr/PokemonTCGAPIClient.cpp | 12 +++--------- oop2eindopdr/PokemonTCGAPIClient.h | 11 +++++++++++ oop2eindopdr/ZipExport.h | 12 ++++++++++-- 8 files changed, 48 insertions(+), 14 deletions(-) diff --git a/oop2eindopdr/CacheManager.cpp b/oop2eindopdr/CacheManager.cpp index c335de3..ff996af 100644 --- a/oop2eindopdr/CacheManager.cpp +++ b/oop2eindopdr/CacheManager.cpp @@ -8,7 +8,6 @@ #include #include -CacheManager::CacheManager(const char* cache_path) : CacheManager(std::string(cache_path)) { } CacheManager::CacheManager(std::string cache_path) { this->cache_path = cache_path; this->verify_cache(); diff --git a/oop2eindopdr/CacheManager.h b/oop2eindopdr/CacheManager.h index 9bd47e3..2aa8a39 100644 --- a/oop2eindopdr/CacheManager.h +++ b/oop2eindopdr/CacheManager.h @@ -13,11 +13,17 @@ private: /** @brief pointers to open file handles */ std::vector files; + /** @brief max amount of attempts for `retry` */ const unsigned int max_tries = 100; /** * @brief retry `action` as long as `retry_if` returns false, until `max_tries` * + * this function runs `action` repeatedly until `retry_if` returns true, or + * `action` has been called `max_tries` times. between each try, there is a + * blocking 1ms delay, so this function should ideally only be used in + * threads, or when `action` has a high probability of succeeding. + * * @param label this label gets printed if retry_count exceeds max_tries * @param check_pre `true` = check `retry_if` before `action`, `false` = check `retry_if` after `action` * @param action this gets executed as long as `retry_if` returns false @@ -30,8 +36,8 @@ private: virtual void retry_if(std::string label, std::function action, std::function retry_if) { retry(label, true, action, retry_if); }; public: /** @brief initialize CacheManager class at `cache_path` */ - CacheManager(const char* cache_path); CacheManager(std::string cache_path); + CacheManager(const char* cache_path) { CacheManager(std::string(cache_path)); }; /** @brief close cache */ virtual ~CacheManager(); /** @brief create cache folder structure */ diff --git a/oop2eindopdr/DownloadManager.h b/oop2eindopdr/DownloadManager.h index c98ae67..08cd7d8 100644 --- a/oop2eindopdr/DownloadManager.h +++ b/oop2eindopdr/DownloadManager.h @@ -4,11 +4,14 @@ #include #include +/** @brief manage threaded downloads */ class DownloadManager { private: const unsigned max_files = 50; + /** @brief download thread list */ std::vector download_queue = {}; + /** @brief fstream pointer list for limiting amount of files open at once */ std::vector file_queue = {}; /** diff --git a/oop2eindopdr/Pokedex.h b/oop2eindopdr/Pokedex.h index ec4ac26..d90bd73 100644 --- a/oop2eindopdr/Pokedex.h +++ b/oop2eindopdr/Pokedex.h @@ -24,15 +24,20 @@ private: /** @brief cache connection */ CacheManager* cache = nullptr; + /** @brief api connection */ PokemonTCGAPIClient* api = nullptr; + /** @brief download manager */ DownloadManager* download_manager = nullptr; + /** @brief allow api access from PokemonCard::fetch_market_value */ friend class PokemonCard; + /** @brief search cache for cards matching query in id or name */ virtual std::vector search_cards_local(std::string query); + /** @brief search API for cards matching query in id or name */ virtual std::vector search_cards_remote(std::string query); - /** @brief convert std::string to lowercase */ + /** @brief [utility] convert std::string to lowercase */ std::string lower(std::string input); public: diff --git a/oop2eindopdr/PokemonCard.h b/oop2eindopdr/PokemonCard.h index ea1a18f..1bbd3c7 100644 --- a/oop2eindopdr/PokemonCard.h +++ b/oop2eindopdr/PokemonCard.h @@ -10,19 +10,26 @@ class Pokedex; /** @brief single pokemon card */ class PokemonCard { private: + /** @brief raw API card data */ nlohmann::json raw_data; + /** @brief load card data from json data (see named constructor) */ virtual void raw_load_json(nlohmann::json raw_data); + /** @brief load card data from cache (see named constructor) */ virtual void raw_load_cache(const char* cache_path); + /** @brief pokedex reference (for API access in ::fetch_market_value) */ Pokedex* pokedex = nullptr; /** @brief add cache path before filename */ virtual std::string prefix_cache_path(const char* filename); + /** @brief thread that creates `complete` file when both images are downloaded */ std::thread* image_download_thread = nullptr; + /** @brief image API url */ std::string url_card_normal = ""; + /** @brief image API url */ std::string url_card_hires = ""; public: @@ -38,6 +45,7 @@ public: double value = 0.f; /** @brief pokemon card current market value */ std::vector attacks = {}; /** @brief list of possible attacks */ + /** @brief get short card identifier: "Name (ID)" */ virtual std::string short_identifier(); /** @brief use API to fetch `this->hp` */ diff --git a/oop2eindopdr/PokemonTCGAPIClient.cpp b/oop2eindopdr/PokemonTCGAPIClient.cpp index 3285f6a..087296d 100644 --- a/oop2eindopdr/PokemonTCGAPIClient.cpp +++ b/oop2eindopdr/PokemonTCGAPIClient.cpp @@ -3,17 +3,11 @@ #include #include -PokemonTCGAPIClient::PokemonTCGAPIClient() { - -} - -PokemonTCGAPIClient::~PokemonTCGAPIClient() { - -} +PokemonTCGAPIClient::PokemonTCGAPIClient() { } +PokemonTCGAPIClient::~PokemonTCGAPIClient() { } nlohmann::json PokemonTCGAPIClient::raw_request(const char* endpoint, cpr::Parameters params) { - std::string full_url = API_URL; - full_url.append(endpoint); + std::string full_url = API_URL + std::string(endpoint); cpr::Response res = cpr::Get(cpr::Url{full_url}, params); return nlohmann::json::parse(res.text); } diff --git a/oop2eindopdr/PokemonTCGAPIClient.h b/oop2eindopdr/PokemonTCGAPIClient.h index cbbcf0d..9910425 100644 --- a/oop2eindopdr/PokemonTCGAPIClient.h +++ b/oop2eindopdr/PokemonTCGAPIClient.h @@ -13,15 +13,26 @@ public: private: const char* API_URL = "https://api.pokemontcg.io/v2"; + /** + * @brief send http(s) GET request to `endpoint` with `params` and return the + * response as parsed JSON + */ virtual nlohmann::json raw_request(const char* endpoint, cpr::Parameters params); + /** @brief get minimal card info for parsing into card (no trading value) */ virtual nlohmann::json raw_get_cards(const char* query); + /** @brief get full card info by card id */ virtual nlohmann::json raw_get_card(const char* id); + /** @brief get list of valid sets */ virtual nlohmann::json raw_get_sets(const char* query); public: + /** @brief get list of cards that contain `query` in name or id field */ virtual std::vector get_cards_by_query(const char* query); + /** @brief get list of cards in set */ virtual std::vector get_set_cards(const char* set_name); + /** @brief get full card info by card id */ virtual PokemonCard* get_full_card(const char* id); + /** @brief get list of valid sets */ virtual std::vector get_sets(); }; diff --git a/oop2eindopdr/ZipExport.h b/oop2eindopdr/ZipExport.h index 741ab4e..0800b41 100644 --- a/oop2eindopdr/ZipExport.h +++ b/oop2eindopdr/ZipExport.h @@ -5,20 +5,28 @@ class Pokedex; +/** @brief handle csv parsing and zip export */ class ZipExport { private: + /** @brief reference to pokedex */ Pokedex* pokedex; - std::string csv_path, zip_path; - std::vector id_list; + std::string csv_path; /** @brief input csv file path */ + std::string zip_path; /** @brief output zip file path */ + std::vector id_list; /** @brief list of id's in csv file */ public: + /** @brief create ZipExport */ ZipExport(); + /** @brief create ZipExport class and immediately start export */ ZipExport(Pokedex* pokedex, std::string input_csv, std::string output_zip); virtual ~ZipExport(); + /** @brief set pokedex reference */ virtual void set_pokedex(Pokedex* pokedex); + /** @brief set csv_path and parse csv file */ virtual void import_csv(std::string filename); + /** @brief generate output export zip file */ virtual void export_zip(std::string filename); }; -- cgit v1.2.3