refl-cpp (v0.8.1) (Documentation)
A compile-time reflection library for modern C++ with support for templates, attributes and proxies 🔥
refl-cpp allows static reflection and inspection of types in C++ with full support for templated types and functions! The metadata required for this is specified through the use of macros (but wait!). The macros require the user to only specify the type that is being reflected and only the names of the members that are of interest. ReflCpp has a small and well-organised API surface.
-
Macro-based code-gen has been minimized as much as is possible to support all basic requirements. All higher-level operations are implemented as free types and function in one of the utility namespaces.
-
Support for autogeneration of reflection metadata through a non-intrusive interface is
coming soonnow available in the form of refl-ht.
- Minimum language standard: C++17
- refl-cpp is packaged as a header-only library! Simply
#include "refl.hpp"
just like any other header.
- MIT License (for more details, see the license file)
-
Introductory post - Compile-time reflection in C++ 17
-
In-depth post - refl-cpp — A deep dive
See contributors.md
refl-cpp is publicly open for any contribution. Bugfixes and new features are welcome. Extra modules are too (as long as the single-header usability is preserved and the functionality is not overly specific to particular use case).
Example metadata declaration (with refl-ht - a lightweight, portable preprocessor)
struct Point {
REFL(/* attributes */) float x;
REFL() float y;
};
Example metadata declaration (without refl-ht)
struct Point {
float x;
float y;
};
/* New style */
REFL_AUTO(
type(Point),
field(x, /* attributes */),
field(y)
)
/* Old style */
REFL_TYPE(Point)
REFL_FIELD(x, /* attributes */)
REFL_FIELD(y)
REFL_END
// Printing an object's properties:
Point pt{};
for_each(refl::reflect(pt).members, [&](auto member) {
std::cout << member.name << "=" << member(pt) << ";";
}
// Result: prints x=0;y=0;
// Converting to an std::tuple: (Note the constexpr!)
constexpr auto values = map_to_tuple(refl::reflect(pt).members, [&](auto member) {
return member(pt);
}
// Result: values == std::tuple<int, int>{ 0, 0 };
- See examples/ for more usage examples.
// Describes a type and all of its members
REFL_AUTO(
type(Name, Attribute...),
field(Name, Attribute...),
func(Name, Attribute...)
)
// Starts the declaration of Type's metadata.
// Must be followed by one of: REFL_END, REFL_FIELD, REFL_FUNC.
// Example: REFL_TYPE(Dog, bases<Animal>)
REFL_TYPE(Type, Attributes...)
// Starts the declaration of Type's metadata.
// Must be followed by one of: REFL_END, REFL_FIELD, REFL_FUNC.
// Example: REFL_TEMPLATE((typename K, typename V), (std::pair<K, V>))
REFL_TEMPLATE((typename... Ts), (Type<Ts...>)), Attributes...)
// End the declaration of Type's metadata.
// Does not have an argument list
REFL_END
// Describes a field.
// Example: REFL_FIELD(first_name, property{ "Value" })
REFL_FIELD(Field, Attributes...)
// Describes a function.
// Example: REFL_FUNC(first_name, property{ "Size" })
REFL_FUNC(Function, Attribute...)
// NOTE: None of the macros above need a terminating semi-colon (;)
Releases follow the MAJOR.MINOR.PATCH
versioning scheme
Major
denotes a very big change in the structure of the library.
Minor
denotes a smaller change, which usually includes new features and might also change or even remove certain features.
Patch
denotes a version which fixed a bug and does not include new features.
- Fixed a bug that prevented the compilation of
refl::descriptor::get_display_name()
in some compilers (thanks to ticelo) - Removed improper usage of
[[maybe_unused]]
that caused warnings under clang.
- Added the ability to create
refl::const_string<N>
instances fromconst char*
which allows using c-strings (const char*
) values from attributes together withconst_string<N>
and inconstexpr
context possible. That feature is exposed by theREFL_MAKE_CONST_STRING(CString)
macro. Important:CString
must be a Core constant expression. The macro is necessary to avoid the duplication of the provided expression and currently expands to ~detail::copy_from_unsized<detail::strlen(CString)>(CString)
. (another thanks to Siapran for contributing the implementation for theconstexpr length()
function.)
- Added
constexpr const_string::substr<Pos, [Count]>()
- Added
make_const_string()
as a shortcut for the creation of empty const strings. - Added
trait::{first, last, tail, init, append, prepend, reverse, concat}
andTraitName_t
equivalents to ease the use oftype_list<...>
. - Breaking change:
trait::map
andtrait::filter
now no longer accept variadic template parameters. Wrap variadic parameters in a type_list. (Allowing bothtype_list<Ts...>
andTs...
is problematic due to cryptic errors when e.g.const type_list<Ts...>
is provided.) - Breaking change:
util::accumulate
now mimics the behaviour ofstd::accumulate
more closely. It relies on the return value of the functor instead of mutating the accumulator argument. The new implementation now allows for the types ofinitial_value
and the return type to differ (thanks to Siapran). - Removed:
util::get<N>(const type_list<Ts...>&)
. Usetrait::get_t<N, type_list<Ts...>>
instead. This is part of a move towards minimizing the duplication between thetrait::
andutil::
namespaces. - Added two new examples: example-binding.cpp and example-dao.cpp to present some of the new things introduced in this release. (example-dao.cpp based on work by Siapran)
- Fixed multiple unused X warnings (fixed by Siapran) #12
- Bugfix: usage of incorrect bound in
operator+(const_string<N>, const_string<M>)
(fixed by Siapran) #11
- Bugfix: clang errors during compilation of reflected overloaded member functions (since 0.6.0)
- Bugfix: Compiler error in clang: refl::attr::property's implicitly-declared default constructor is deleted due to N3797 §8.5/7 #9
- Bugfix: const_string::operator std::string() was incorrectly marked as constexpr which caused compilation failure in non-C++20-compliant compilers
- Changed: property() is now only usable on function members / use contract based checks for functions and fields (is_readable/writable)
- Removed: read_only, write_only, read_write access modifiers for property() attributes (rw-detection now based on contract).
- Added:
type_descriptor<T>::type
as an alias forT
. - Added:
function_descriptor<T, N>::pointer
which points to the target function, if the pointer can be resolved and to nullptr otherwise. - Added:
function_descriptor<T, N>::is_resolved
for checking whether the pointer to the function has been resolved successfully. - Added:
function_descriptor<T, N>::resolve<Pointer>
for explicitly resolving the function pointer as a value of the specified type. - Added:
util::get<size_t N>(type_list<Ts...>&&)
which zero-initializes and returns the type at the N-th position. - Added:
util::get<size_t N>(Tuple&&)
as an alias forstd::get<N>
.
- Bugfix: The REFL_AUTO macro was not working properly in MSVC and led to Internal compiler errors
- Changed: As a result of the related bugfix, the REFL_AUTO macro has been stabilized and its use is now recommended
- Removed deprecated macros
$refl(...)
,REFL_UNSTABLE(...)
,REFL_DEPRECATED(...)
- Removed deprecated
refl::attr::access_type::read, write
constants. Replaced by read_only, write_only for consistency. - Removed deprecated
refl::attr::read_only, read_write, write_only
constants. Use the enum-qualified values. The constants are still available unqualified in macro context. - Removed refl::descriptor::make_invoker (which was not deprecated but is now obsolete.) Simply replace make_invoker(x) with x.
- The defaulted constructor for
refl::util::const_string<N>
was replaced by a user-declared default constructor which now always zero-initializes the string buffer.
- Added:
trait::is_type[_v]
,descriptor::is_type(const T&)
for checking whether a type is a type_descriptor instance.
trait::as_type_list
now supports reference type in place ofT<Ts...>
(e.g.std::tuple<Ts...>&
->type_list<Ts...>
).refl::attr::access_type::{read, write}
now deprecated, replaced by{read_only, write_only}
(Note: implicitly-usableread_only
,write_only
constants in attribute (inREFL_...
macros) context remain unchanged)refl::descriptor::field_descriptor::operator()
now supports acting as a setter.refl::descriptor::make_invoker
is now no longer needed and marked as deprecated.
- Renamed:
trait::filter
totrait::filter_t
, replaced bystruct trait::filter { typedef ... type; }
to follow preset convention - Renamed:
trait::map
totrait::map_t
, replaced bystruct trait::map { typedef ... type; }
to follow preset convention - Breaking change:
function_descriptor<...>::pointer
now no longer exists. (Reason: Replacing with forwarding function allows for more flexibility when usingrefl::runtime::proxy<>
. Migrate by taking a pointer tofunction_descriptor<...>::invoke()
) - Breaking change: trait::contains/base/instance now no longer work implicitly with
std::tuple<...>
or support variadic arguments. Usetype_list<>
ortrait::as_type_list_t
to migrate working code. (Reason: Specializations found to be causative to many recently discovered bugs and are error-prone.) - Bugfix: faulty implementation of
trait::skip<N>
- Bugfix: faulty implementation of
util::to_tuple
- Bugfix:
trait::contains_base
was working the other way around (checking for presense of base of a specified type, instead of checking for a derived type with a specified base)
- Bugfix:
type_info__<T*>
has name defined aschar[N]
instead ofconst_string<N>
- added new experimental syntax for metadata declaration that makes use of variadic macro expansion (can be disabled with
REFL_NO_VARIADICS
)
REFL_AUTO
(
type(User), // expands to REFL_TYPE(User)
field(id, property(read_only)), // expands to REFL_FIELD(id, property(read_only))
field(email),
field(first_name, property("firstName")),
field(last_name, property("lastName"))
func(save_to_db) // expands to REFL_FUNC(save_to_db)
) // REFL_END appended automatically
refl::util::const_string<N>
can now be directly compared for equality withchar[M]
refl::util::const_string<N>
can now be concatenated withchar[M]
refl::runtime::debug
now captures values of member invocations by universal references (previous implementations required a copy of the value)refl::runtime::debug
now does not require the members of composites to be reflectable. (members that cannot be printed get replaced with<?>
).refl::trait::is_reflectable
now discards cv-qualifiers -> all cv-qualified types are now also reflectable.
refl::descriptor::is_writable
now correctly supports field descriptors- most of
refl.hpp
is now not included whenREFL_PREPROCESSOR
is defined (optimization for refl-ht)
- added new
REFL(...)
macro for annotation of reflectable members (replaces$refl(...)
) $refl(...)
macro usage now deprecated
- added support for refl-ht (the refl-cpp header tool)
- added
refl::util::contains(type_list<...>, [predicate]), refl::util::contains(type_list<...>, const_string<N>)
- removed
refl::attr::is_readable/is_writable
(userefl::descriptor::is_readable/is_writable
instead; reason: lack of support for fields that lack a property attribute)
refl::runtime::proxy<Derived, Target>
can now delegate field 'invocations'. (Methods with names matching those of the reflected fields are created.)refl::attr::property
now can take an optionalrefl::attr::access_type
(values:read_only
,write_only
,read_write
) to specify whether the property is considered readable or writable (or both).- added
refl::descriptor::is_readable/is_writable
- added
refl::attr::is_readable/is_writable