diff --git a/src/yycc/carton/binstore.hpp b/src/yycc/carton/binstore.hpp index 1a70614..6903a36 100644 --- a/src/yycc/carton/binstore.hpp +++ b/src/yycc/carton/binstore.hpp @@ -5,4 +5,25 @@ #include "binstore/configuration.hpp" #include "binstore/storage.hpp" +/** + * @brief The main namespace for the binstore module. + * @details + * The binstore module provides a binary settings storage system that allows + * applications to persistently store and retrieve configuration settings in + * a binary format. It includes functionality for: + * + * \li Type-safe serialization and deserialization of various data types + * (integers, floating-point numbers, booleans, strings, enums) + * \li Setting management with unique tokens for access control + * \li Version control for configuration data with migration strategies + * \li File and stream-based storage operations + * \li Comprehensive error handling for robust operation + * + * The main components are: + * \li types: Basic types and error handling for the module + * \li serdes: Serialization/deserialization functionality for different data types + * \li setting: Management of settings with name-based lookup and token-based access + * \li configuration: Version and settings collection management + * \li storage: Main storage class for loading/saving settings to/from files or streams + */ namespace yycc::carton::binstore {} diff --git a/src/yycc/carton/binstore/configuration.hpp b/src/yycc/carton/binstore/configuration.hpp index a19ecbe..75fd3e2 100644 --- a/src/yycc/carton/binstore/configuration.hpp +++ b/src/yycc/carton/binstore/configuration.hpp @@ -8,14 +8,28 @@ namespace yycc::carton::binstore::configuration { + /// @brief Configuration class that holds version and settings for the binstore module. class Configuration { public: + /** + * @brief Construct a new Configuration object. + * @param[in] version The version identifier for this configuration. + * @param[in] settings The settings collection to associate with this configuration. + */ Configuration(NS_YYCC_BINSTORE_TYPES::VersionIdentifier version, NS_YYCC_BINSTORE::setting::SettingCollection&& settings); ~Configuration(); YYCC_DEFAULT_COPY_MOVE(Configuration) public: + /** + * @brief Get the version identifier of this configuration. + * @return The version identifier. + */ NS_YYCC_BINSTORE_TYPES::VersionIdentifier get_version() const; + /** + * @brief Get the settings collection associated with this configuration. + * @return A const reference to the settings collection. + */ const NS_YYCC_BINSTORE::setting::SettingCollection& get_settings() const; private: diff --git a/src/yycc/carton/binstore/setting.hpp b/src/yycc/carton/binstore/setting.hpp index 298102c..97ccbbc 100644 --- a/src/yycc/carton/binstore/setting.hpp +++ b/src/yycc/carton/binstore/setting.hpp @@ -1,3 +1,7 @@ +/** + * @file setting.hpp + * @brief Setting management for the binstore module. + */ #pragma once #include "../../macro/class_copy_move.hpp" #include "types.hpp" @@ -11,47 +15,107 @@ namespace yycc::carton::binstore::setting { + /// @brief Represents a single setting with a name. class Setting { public: + /** + * @brief Construct a new Setting object. + * @param[in] name The name of the setting. + */ Setting(const std::u8string_view& name); ~Setting(); YYCC_DEFAULT_COPY_MOVE(Setting) public: + /** + * @brief Get the name of the setting. + * @return A u8string_view of the setting name. + */ std::u8string_view get_name() const; private: std::u8string name; }; + /// @brief Represents a registered setting with both a token and setting information. class RegisteredSetting { public: + /** + * @private + * @brief Construct a new Registered Setting object. + * @param[in] token The unique token for the setting. + * @param[in] setting The setting information. + */ RegisteredSetting(NS_YYCC_BINSTORE_TYPES::Token token, Setting&& setting); ~RegisteredSetting(); YYCC_DEFAULT_COPY_MOVE(RegisteredSetting) public: + /** + * @brief Get the token associated with this registered setting. + * @return The token. + */ NS_YYCC_BINSTORE_TYPES::Token get_token() const; + + /** + * @brief Get the setting instance associated with this registered setting. + * @return A const reference to the setting. + */ const Setting& get_setting() const; private: - NS_YYCC_BINSTORE_TYPES::Token token; - Setting setting; + NS_YYCC_BINSTORE_TYPES::Token token; ///< The unique token for the setting. + Setting setting; ///< The setting instance. }; + /// @brief Collection of settings with name-based lookup and token-based access. class SettingCollection { public: + /// @brief Construct a new Setting Collection object. SettingCollection(); ~SettingCollection(); YYCC_DEFAULT_COPY_MOVE(SettingCollection) public: + /** + * @brief Add a setting to the collection. + * @param[in] setting The setting to add. + * @return The token assigned to the setting. + */ NS_YYCC_BINSTORE_TYPES::Token add_setting(Setting&& setting); + /** + * @brief Find a setting by its name. + * @param[in] name The name of the setting to find. + * @return An optional token if the setting was found, std::nullopt otherwise. + */ std::optional find_name(const std::u8string_view& name) const; + /** + * @brief Check if a setting with the given token exists. + * @param[in] token The token to check. + * @return True if the setting exists, false otherwise. + */ bool has_setting(NS_YYCC_BINSTORE_TYPES::Token token) const; + /** + * @brief Get a setting by its token. + * @param[in] token The token of the setting to get. + * @return A const reference to the setting. + * @exception May throw if the token is invalid. + */ const Setting& get_setting(NS_YYCC_BINSTORE_TYPES::Token token) const; + /** + * @brief Get all registered settings. + * @return A const reference to the vector of registered settings. + */ const std::vector& all_settings() const; + /** + * @brief Get the number of settings in the collection. + * @return The number of settings. + */ size_t length() const; + /** + * @brief Check if the collection is empty. + * @return True if empty, false otherwise. + */ bool empty() const; private: @@ -59,6 +123,6 @@ namespace yycc::carton::binstore::setting { std::vector settings; }; -} +} // namespace yycc::carton::binstore::setting #undef NS_YYCC_BINSTORE_TYPES diff --git a/src/yycc/carton/binstore/storage.hpp b/src/yycc/carton/binstore/storage.hpp index 69dac5d..0e20d46 100644 --- a/src/yycc/carton/binstore/storage.hpp +++ b/src/yycc/carton/binstore/storage.hpp @@ -1,3 +1,7 @@ +/** + * @file storage.hpp + * @brief Storage management for the binstore module. + */ #pragma once #include "../../macro/class_copy_move.hpp" #include "types.hpp" @@ -45,6 +49,7 @@ namespace yycc::carton::binstore::storage { AcceptAll, }; + /// @brief Main storage class for managing binary settings storage. class Storage { private: /** @@ -56,15 +61,46 @@ namespace yycc::carton::binstore::storage { NS_YYCC_BINSTORE_CFG::Configuration cfg; ///< The configuration associated with this storage. public: + /** + * @brief Construct a new Storage object. + * @param[in] cfg The configuration to associate with this storage. + */ Storage(NS_YYCC_BINSTORE_CFG::Configuration&& cfg); ~Storage(); YYCC_DEFAULT_COPY_MOVE(Storage) public: - NS_YYCC_BINSTORE_TYPES::BinstoreResult load_from_file(const std::filesystem::path& fpath, LoadStrategy strategy = LoadStrategy::MigrateOld); + /** + * @brief Load settings from a file. + * @param[in] fpath Path to the file to load from. + * @param[in] strategy The load strategy to use. Defaults to MigrateOld. + * @return A BinstoreResult indicating success or failure. + */ + NS_YYCC_BINSTORE_TYPES::BinstoreResult load_from_file(const std::filesystem::path& fpath, + LoadStrategy strategy = LoadStrategy::MigrateOld); + + /** + * @brief Load settings from an input stream. + * @param[in] s The input stream to load from. + * @param[in] strategy The load strategy to use. Defaults to MigrateOld. + * @return A BinstoreResult indicating success or failure. + */ NS_YYCC_BINSTORE_TYPES::BinstoreResult load(std::istream& s, LoadStrategy strategy = LoadStrategy::MigrateOld); + + /** + * @brief Save settings to a file. + * @param[in] fpath Path to the file to save to. + * @return A BinstoreResult indicating success or failure. + */ NS_YYCC_BINSTORE_TYPES::BinstoreResult save_into_file(const std::filesystem::path& fpath); + + /** + * @brief Save settings to an output stream. + * @param[in] s The output stream to save to. + * @return A BinstoreResult indicating success or failure. + */ NS_YYCC_BINSTORE_TYPES::BinstoreResult save(std::ostream& s); + /** * @brief Clear all raw data saved in internal cache. * @details This will cause every setting was set in default value when user fetching them. diff --git a/src/yycc/carton/clap.hpp b/src/yycc/carton/clap.hpp index 0f893cc..083008d 100644 --- a/src/yycc/carton/clap.hpp +++ b/src/yycc/carton/clap.hpp @@ -10,5 +10,21 @@ #include "clap/resolver.hpp" // TODO: Support multiple arguments for single option. - +/** + * @brief Command Line Argument Parser (CLAP) module for handling command line arguments and environment variables. + * @details This module provides a comprehensive system for defining, parsing, and validating command line + * arguments and environment variables. It includes components for defining application metadata, + * command line options, variables, and utilities for parsing and validation. + * + * The main components include: + * \li Types: Error types and result types used throughout the module + * \li Validator: Type-safe validation for command line argument values + * \li Option: Command line options with short and long names + * \li Variable: Environment variables that can be captured + * \li Summary: Application metadata (name, version, author, description) + * \li Application: Complete application definition with options and variables + * \li Manual: Help and version information generation + * \li Parser: Command line argument parsing functionality + * \li Resolver: Environment variable resolution functionality + */ namespace yycc::carton::clap {}