yyc12345/YYCCommonplace
1
0
Fork 0
Code Activity

doc: add doxygen comment for code

Browse Source
This commit is contained in:
yyc12345
2025-12-23 21:21:34 +08:00
parent cc5e6239ba
commit 408ea5ef33
5 changed files with 156 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

21
src/yycc/carton/binstore.hpp
View File

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

14
src/yycc/carton/binstore/configuration.hpp
View File

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

70
src/yycc/carton/binstore/setting.hpp
View File

@@ -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<NS_YYCC_BINSTORE_TYPES::Token> 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<RegisteredSetting>& 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<RegisteredSetting> settings;
};
}
} // namespace yycc::carton::binstore::setting
#undef NS_YYCC_BINSTORE_TYPES

38
src/yycc/carton/binstore/storage.hpp
View File

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

18
src/yycc/carton/clap.hpp
View File

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