From ee6daf36d78dec513c2bb3f730ccf9cee7b150e9 Mon Sep 17 00:00:00 2001 From: Maddie Busig Date: Tue, 29 Apr 2025 05:31:06 -0700 Subject: [PATCH] Comment ruleset functions --- include/fractal.hpp | 108 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/include/fractal.hpp b/include/fractal.hpp index da10e67..efb2234 100644 --- a/include/fractal.hpp +++ b/include/fractal.hpp @@ -99,20 +99,128 @@ private: etl::vector m_mark_rules; public: + /** + * @brief Checks if the maximum number of tokens has been reached + * + * @ret @c true if the number of tokens in the ruleset equals @c S_MAX_TOKENS, @c false otherwise + */ bool tokens_full() const; + + /** + * @brief Add new token variable that can be used in this ruleset + * + * @param type Type of the token to add + * @param value Value of the token, unused if @p type is @c token_type_e::empty + * + * @ret @c token_id_t of the newly added token, local to this ruleset + * + * @exception @c mtl::invalid_argument if the given token type is invalid + * @exception @c mtl::length_error if the maximum number of tokens is reached + */ token_id_t add_token(token_type_e type, mtl::fixed value = 0); + /** + * @brief Checks if the maximum number of group characteristics has been reached + * + * @ret @c true if the number of group characteristics in the ruleset equals @c S_MAX_CGROUPS, @c false otherwise + */ bool group_characteristics_full() const; + + /** + * @brief Add new group characteristic + * + * @param tokens @c etl::ivector of @c token_id_t that should be generated inside this group + * @param factor The number of times the group's tokens are repeatedly generated + * + * @ret @c group_id_t of the newly added group characteristic, local to this ruleset + * + * @exception mtl::invalid_argument if an invalid token was encountered + * @exception mtl::length_error if the maximum number of groups is reached + */ group_id_t add_group_characteristic(const etl::ivector& tokens, uint32_t factor = 1); + /** + * @brief Checks if the maximum number of weighted groups has been reached + * + * @ret @c true if the number of weighted groups in the ruleset equals @c S_MAX_WGROUPS, @c false otherwise + */ bool weighted_groups_full() const; + + /** + * @brief Add new weighted group + * + * Adds weighted group of groups, where each subgroup has a + * (weight) / (total weight) chance of being selected. Weights + * are represented as @c uint32_t. + * + * @param weights @c etl::ivector of @c etl::pair of @c group_id_t and their corresponding weights + * + * @ret @c weighted_group_id_t of the newly created group + * + * @exception @c mtl::invalid_argument if no groups were supplied, or an invalid group was encountered + * @exception @c mtl::length_error if the maximum number of groups is reached + */ weighted_group_id_t add_weighted_group(const etl::ivector& groups); + /** + * @brief Checks if the maximum number of branch rules has been reached + * + * @ret @c true if the number of branch rules in the ruleset equals @c S_MAX_BRANCH_RULES, @c false otherwise + */ bool branch_rules_full() const; + + /** + * @brief Add a new unweighted branch rule to the ruleset + * + * Branch rules describe what groups can be generated given a token. + * Branch rules can use either plain groups or weighted groups as their output. + * + * @param match Token to match and generate the group in place of + * @param group Group to generate + * + * @ret @c branch_rule_id_t of the newly added branch rule + * + * @exception @c mtl::invalid_argument if an invalid token or group was supplied + * @exception @c mtl::length_error if the maximum number of branch rules was reached + */ branch_rule_id_t add_branch_rule(token_id_t match, group_id_t group); + + /** + * @brief Add a new weighted branch rule to the ruleset + * + * Branch rules describe what groups can be generated given a token. + * Branch rules can use either plain groups or weighted groups as their output. + * + * @param match Token to match and generate the group in place of + * @param wgroup Weighted group to select from, only one subgroup is generated + * + * @ret @c branch_rule_id_t of the newly added branch rule + * + * @exception @c mtl::invalid_argument if an invalid token or group was supplied + * @exception @c mtl::length_error if the maximum number of branch rules was reached + */ branch_rule_id_t add_branch_rule_weighted(token_id_t match, weighted_group_id_t wgroup); + /** + * @brief Checks if the maximum number of mark rules has been reached + * + * @ret @c true if the number of mark rules in the ruleset equals @c S_MAX_MARK_RULES, @c false otherwise + */ bool mark_rules_full() const; + + /** @brief Add a new marking rule to the ruleset + * + * Mark rules describe what tokens should have their positions output + * each generation. If a token has a match, its position and a tag is output. + * + * @param match Token to match and mark + * @param tag Marking identifier, does not need to be unique + * + * @ret @c mark_rule_id_t of the newly added mark rule + * + * @exception @c mtl::invalid_argument if an invalid token was supplied + * @exception @c mtl::length_error if the maximum number of mark rules was reached + */ mark_rule_id_t add_mark_rule(token_id_t match, uint32_t tag); };