flag.hpp File Reference

Compile-time named flags grouped into categories, plus a runtime FlagSet, a program-wide GlobalFlagRegistry, and declaration macros. More...

#include <commons/display_info.hpp>
#include <commons/fixed_string.hpp>
#include <commons/types.hpp>
#include <algorithm>
#include <concepts>
#include <map>
#include <optional>
#include <string_view>
#include <utility>
#include <vector>

Include dependency graph for flag.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	comms::FlagCategory< Name >
	A flag category, identified by a FixedString name. More...
struct	comms::UnsetFlagCategory
	The default category for a Flag declared without an explicit one. More...
struct	comms::Flag< Name, Category >
	A compile-time flag: a distinct type named by Name and belonging to Category (defaulting to UnsetFlagCategory). More...
struct	comms::FlagRef
	A type-erased, non-owning runtime handle to a flag. More...
class	comms::FlagSet
	An insertion-ordered set of unique flags, deduplicated by name. More...
class	comms::GlobalFlagRegistry
	A program-wide registry of every known flag. More...
struct	comms::FlagRegistrar< F >
	A self-registering object: constructing one registers F into the GlobalFlagRegistry. More...
class	comms::IHasFlags
	Abstract read-only view of a type that owns a FlagSet. More...
class	comms::HasFlags< Categories >
	Implementation of IHasFlags: embeds a FlagSet and exposes it publicly. More...
class	comms::FlagBuilderMixin< Derived, Categories >
	CRTP helper for builders. More...
class	comms::FlagBuilderGetters< Derived, Categories >
	A builder that is also observable: combines FlagBuilderMixin's fluent mutators with a public, IHasFlags-backed read API. More...

Concepts
concept	comms::AnyFlagCategory
	Any type that exposes a name convertible to std::string_view — satisfied by FlagCategory<Name> and types deriving from it.
concept	comms::AnyFlag
	Any flag type: a name plus a category member type that is itself an AnyFlagCategory.
concept	comms::FlagInCategory
	A flag whose category is exactly Category.
concept	comms::AllowedFlag
	Whether flag F may go into a set constrained to Categories...: any flag when the list is empty (unconstrained), otherwise only flags whose category is one of Categories....

Macros
#define	COMMONS_FLAG_CATEGORY(Ident, Name)    struct Ident : ::comms::FlagCategory<Name> {}
	Declare a flag category type Ident named Name.
#define	COMMONS_FLAG(Ident, Name)    struct Ident : ::comms::Flag<Name> {}
	Declare a flag type Ident named Name in UnsetFlagCategory.
#define	COMMONS_FLAG_IN(Ident, Name, Cat)    struct Ident : ::comms::Flag<Name, Cat> {}
	Declare a flag type Ident named Name in category Cat.
#define	COMMONS_REGISTER_FLAG(Ident)    inline const ::comms::FlagRegistrar<Ident> commons_flag_registrar_##Ident {}
	Register an already-defined flag type Ident into the GlobalFlagRegistry.
#define	COMMONS_DEFINE_FLAG(Ident, Name)
	Define a flag type Ident named Name and auto-register it.
#define	COMMONS_DEFINE_FLAG_IN(Ident, Name, Cat)
	Define a flag type Ident named Name in category Cat and auto-register it.
#define	COMMONS_FLAG_FAMILY(CatIdent, Name, FlagTmpl, ConceptName)
	Declare a whole flag family in one line: a category CatIdent named Name, a per-category flag template FlagTmpl<N>, and a concept ConceptName satisfied by flags in that category.

Detailed Description

Compile-time named flags grouped into categories, plus a runtime FlagSet, a program-wide GlobalFlagRegistry, and declaration macros.

A comms::Flag<Name, Category> is a distinct type identified by a FixedString name and belonging to a comms::FlagCategory<Name> (defaulting to comms::UnsetFlagCategory). Both the name and the category name are exposed as static constexpr std::string_view members — mirroring IconifySet<Set>::set — so they live in the flag type's static, NTTP-backed storage and stay valid for the whole program.

A flag may carry presentation metadata: give it a static const DisplayInfo& display_info() member (see commons/display_info.hpp) and it becomes Displayable; FlagRef::of<F>() then captures a pointer to it. Flag does not inherit the display trait, so a plain flag is simply not Displayable.

comms::FlagRef is a type-erased, non-owning runtime handle (name + category + optional display pointer) whose views point at that static storage. comms::FlagSet is an insertion-ordered set of unique flags (deduplicated by name) exposing std::set-style methods plus group_by_category(). comms::GlobalFlagRegistry is a Meyers singleton that knows about every registered flag.

Flags self-register through the define macros (each emits a self-registering inline object) or explicitly via COMMONS_REGISTER_FLAG / GlobalFlagRegistry::add.

A small family of mixins lets a type own a FlagSet. comms::IHasFlags is the abstract read interface (flags() / has_flag()) for polymorphic access; comms::HasFlags<Categories...> implements it as a plain holder. comms::FlagBuilderMixin<Derived, Categories...> (CRTP) adds fluent set/insert/remove mutators returning Derived& while keeping read access private (a "silent" builder), and comms::FlagBuilderGetters<Derived, Categories...> combines those mutators with the public, IHasFlags-backed read API. Listing Categories... constrains the typed overloads to flags in those categories; an empty list accepts any flag.

Serialization (in commons/json.hpp, gated by COMMONS_WITH_NLOHMANN_JSON): a FlagRef travels as its name string and a FlagSet as a JSON array of names; reading them back resolves each name against the GlobalFlagRegistry.