Ocead's Reflection Library

A single-include library for reflection in C++ programs

Example

With reflection	Without reflection
#include <string> #include <ocead/reflection.hpp> class example : public ocead::reflection { REFLECTIVE(example)( PROP(int, 1000, number); PROP(public:, std::string, 1001, text) = "Gnampf"; double non_reflective_0; FUNC(public:, void, 2000, add, (int summand)) { number += summand; } FUNC(std::string const &, 2001, get_text, () const) { return text; } void non_reflective_1(); CTOR(example, 3000, ()) = default; CTOR(example, 3001, (int n, std::string && t)) : number(n), text(t) { } DTOR(example, 4000) = default; ); private: double non_reflective_2 = 6.; };	#include <string> class example { private: int number; public: std::string text = "Gnampf"; double non_reflective_0; public: void add(int summand) { number += summand; } public: std::string const & get_text() const { return text; } void non_reflective_1(); example() = default; example(int n, std::string && t) : number(n), text(t) { } ~example() = default; private: double non_reflective_2 = 6.; };

With reflection

Without reflection

#include <string>
#include <ocead/reflection.hpp>

class example : public ocead::reflection {
    REFLECTIVE(example)(
      PROP(int, 1000, number);
      PROP(public:, std::string, 1001, text) = "Gnampf";
      double non_reflective_0;
      
      FUNC(public:, void, 2000, add, (int summand)) {
          number += summand;
      }
      
      FUNC(std::string const &, 2001, get_text, () const) {
          return text;
      }
      
      void non_reflective_1();
      
      CTOR(example, 3000, ()) = default;
      
      CTOR(example, 3001, (int n, std::string && t))
          : number(n),
            text(t) { }
      
      DTOR(example, 4000) = default;
    );
    
    private:
    double non_reflective_2 = 6.;
};

#include <string>


class example {
    
    private: int number;
    public: std::string text = "Gnampf";
    double non_reflective_0;
    
    public: void add(int summand) {
      number += summand;
    }
    
    public: std::string const & get_text() const {
      return text;
    }
    
    void non_reflective_1();
    
    example() = default;
    
    example(int n, std::string && t)
      : number(n),
        text(t) { }
    
    ~example() = default;
    
    
    private:
    double non_reflective_2 = 6.;
};

Requirements

GNU GCC or Clang supporting C++17
RTTI is not required

Usage

(The following examples are based on the example class from the example above)

Writing reflective classes

With the macros described below, class-wide unique IDs are added to the classes symbols. With these IDs, the reflective symbols can be accessed dynamically at runtime. By default the type of these IDs is std::size_t, but you can replace it with any type that produces compile time constant expressions.

ℹ I recommend enum classes as a type for class-wide unique IDs.

Reflective blocks

Each class definition may contain a reflective block. This block is either delimited by the

BEGIN_REFLECTIVE(example);
...
END_REFLECTIVE();

macros, or contained within the

REFLECTIVE(example)(
    ...
)

macro, here with example as the reflective classes name. All reflective symbols must appear in these blocks.

ℹ Reflective blocks may also contain non-reflective symbols. The other way round is non possible.

Properties

Reflective properties can be declared with the PROP macro, like so:

PROP(public:, std::string, 1001, text) = "Gnampf";

Here:

public: is the access specifier for the reflective property (can be omitted)
std::string the type of the reflective property
1001 the class-wide unique ID for the reflective symbol
text the name of the reflective property
= "Gnammpf" the optional default initializer for the reflective symbol

Without access specifier the same declaration would look like this:

PROP(std::string, 1001, text) = "Gnampf";

In this case, the reflective property is private by default.

Functions

Reflective functions can be declared with the FUNC macro, like so:

FUNC(public: void, 2000, add, (int summand)) {
    number += summand;
}

Here:

public: is the access specifier for the reflective function (can be omitted)
void the return type of the reflective function
2000 the class-wide unique ID for the reflective symbol
add the name of the reflective function
(int summand) the parameter list of the function and optional const qualifier
{ number += summand; } the optional function body following the declaration

If the access specifier is omitted, it defaults to public.

Constructors

Reflective constructors can be declared almost like functions, but with the CTOR macro instead:

CTOR(public: explicit, example, 3001, (int n, std::string && t))
    : number(n),
      text(t) { }

Here:

public: explicit is the access specifier for the reflective constructor and optional explicit specifier (can be omitted)
example the class name
3001 the class-wide unique ID for the reflective symbol
(int n, std::string && t) the parameter list of the constructor
: number(n), text(t) { } the optional initializer list and constructor body

If the access specifier is omitted, it defaults to public.

Destructors

Reflection destructor can be declared almost like constructors, but with the DTOR macro instead:

DTOR(public:, example, 4000) = default;

Here:

public: is the access specifier for the reflective destructor (can be omitted)
example the class name
4000 the class-wide unique ID for the reflective symbol
= default the implementation of the destructor

Again, if the access specifier is omitted, it defaults to public.

Obtaining class descriptors

Class descriptors provide you with reflective information at runtime. To obtain a class descriptor of a reflective class, use the ocead::reflect template function, like so:

const auto & refl = ocead::reflect<example>();

If you have RTTI enabled for your program, you can additionally obtain a classes class descriptor by calling the overridden ocead::reflective::reflect function, like so:

example instance;
const auto & refl = instance.reflect();

These descriptors map the class-wide unique IDs to symbol descriptors that contain information such as name, type and, depending on the kind of symbol, various function pointers.

Accessing member fields

Typed / Untyped

The difference in calling typed and untyped accessors is where the class-wide unique ID goes:

For typed accessors the ID becomes a template parameter
```
auto & number = refl.access<1000>(instance);
```

For untyped accessors the ID is a regular parameter

auto & number = *static_cast<int &>(refl.access(&instance, 1000));

For each access function a const_access function for accessing const objects exists.

Access by function / offset

Normally, reflective properties are accesses via generated functions that return the property. For faster access you may use access by offset. Only reflective properties that aren't references can also be accessed by offset from a pointer to an object.

⚠ Accessing members of non standard-layout types is only conditionally supported. Check if your compiler supports offset accessing before using this feature!

The functions for access by offset are offset_access and const_offset_access. They can be called just like their non-offset_ counterparts.

Invoking member functions

Reflective functions can be invoked with the invoke functions in class and symbol descriptors. The call depends on what you know at compile time:

If you know the ID at compile time:

auto sum = refl.invoke<int, 2000>(&instance, 5);

If you don't know the ID at compile time:
```
auto sum = refl.invoke_return<int>(&instance, 2000, 5);
```
For the ID-known-at-compile-time variant you only need the invoke function. For the ID-known-at-run-time variant you have to discern whether to use the invoked functions return value, in which case you have to call invoke_return instead, or not. Then it is:
```
refl.invoke(&instance, 2000, 5);
```

In any case, you pass a pointer to the object on which the reflective function shall be invoked on, then the optional id, followed by the arguments with which to call the function. Pass the arguments just as you would when calling std::invoke.

Feedback and suggestions in regard to resolving the ambiguity between invocations a very welcome.

Constructing instances

Constructing reflective objects is very straightforward. You can construct an instance of a reflective class in one of three ways:

new

void * instance = refl.construct(3001, 6, std::string(""));

This constructs the instance using new.

placement new

alignas(example) std::byte buffer[sizeof(example)];
void * instance = refl.placement_construct(buffer, 3001, 6, std::string(""));

This constructs the instance using placement new.

shared new
```
auto instance_ptr = refl.shared_construct(buffer, 3001, 6, std::string(""));
```
This constructs the instance using new and returns a smart pointer to the instance.

As with invocations, if you know the class-wide unique ID at compile time, you may pass is as a template parameter.

Destroying instances

Destroying reflective objects is even simpler:

Calling destructors
```
refl.destroy(4000, &instance);
```
This calls the destructor in instance.
Deallocating instances
```
refl.dealloc_destroy(4000, &instance);
```
This calls the destructor in instance and deallocates the occupied memory. Use it just as you would use delete.

Records

You can generate arbitrary record classes from reflective classes, that contain only the member fields you need, like so:

auto rec = ocead::make_record<1000, 1001>(instance);

The template parameters are the IDs of the properties you want to include into the record. You can access the records properties with std::get:

int number = std::get<1000>(rec);

Customization

You may customise this library by overriding different macros.

These macros control the types employed by the library:

Macro	Default type	Description
`OCEAD_REFLECTION_COUNTER_TYPE`	`std::size_t`	Used for globally distinguishing reflective symbols
`OCEAD_REFLECTION_ID_TYPE`	`std::size_t`	Used as unique identifier by `OCEAD_REFLECTION_CLASS_DESCRIPTOR_TYPE`
`OCEAD_REFLECTION_TYPEID_TYPE`	`char const *`	Used for differentiating (return) types of reflective symbols
`OCEAD_REFLECTION_NAME_TYPE`	`char const *`	Used for recording names of reflective symbols
`OCEAD_REFLECTION_CONTAINER_TEMPLATE`	`ocead::reflection::type_identity`	May be used to transform the apparent type of a reflective property into a more complex type
`OCEAD_REFLECTION_ACCESSOR_TYPE`	`ocead::accessor_t`	Function type for non-const accessors
`OCEAD_REFLECTION_CONST_ACCESSOR_TYPE`	`ocead::const_accessor_t`	Function type for const accessors
`OCEAD_REFLECTION_INVOKER_TYPE`	`ocead::invoker_t`	Function type for non-const invokers
`OCEAD_REFLECTION_CONST_INVOKER_TYPE`	`ocead::const_invoker_t`	Function type for const invokers
`OCEAD_REFLECTION_SHARED_PTR_TYPE`	`std::shared_ptr<void>`	Smart pointer type that can hold deleter functions
`OCEAD_REFLECTION_SYMBOL_DESCRIPTOR_TYPE`	`ocead::reflection::symbol_descriptor`	Type used for describing single reflective symbols
`OCEAD_REFLECTION_REFLECTOR_MAP_TYPE`	`std::map`	Type used for organizing `OCEAD_REFLECTION_SYMBOL_DESCRIPTOR_TYPE`
`OCEAD_REFLECTION_CLASS_DESCRIPTOR_TYPE`	`ocead::reflection::class_descriptor`	Type used for describing reflective classes

These macros control how other macros in this library are expanded:

Macro	Default expansion	Description
`OCEAD_REFLECTION_IDENTIFIER_MACRO(type)`	`ocead::reflection::typename_hash(#type)`	Produces `OCEAD_REFLECTION_TYPEID_TYPE` from the name of the type
`OCEAD_REFLECTION_ADD_PREFIX(symbol)`	`_reflection_##symbol`	Macro for modifying the names of additionally generated symbols
`OCEAD_REFLECTION_DEFAULT_PROPERTY_VISIBILITY`	`private:`	The default visibility of reflective properties
`OCEAD_REFLECTION_DEFAULT_FUNCTION_VISIBILITY`	`public:`	The default visibility of reflective functions
`OCEAD_REFLECTION_DEFAULT_CONSTRUCTOR_VISIBILITY`	`public:`	The default visibility of reflective constructors
`OCEAD_REFLECTION_DEFAULT_DESTRUCTOR_VISIBILITY`	`public:`	The default visibility of reflective destructors

You can disable reflection by defining the

OCEAD_NO_REFLECTION

macro. If defined, the macros for reflective symbols expand only to the declaration of the symbols.

Roadmap

License

The code in this repository is distributed under the Boost Software License Version 1.0.

See the code file or the LICENSE file for the full license text.

Ocead / reflection

Ocead's Reflection Library

Example

Requirements

Usage

Writing reflective classes

Reflective blocks

Properties

Functions

Constructors

Destructors

Obtaining class descriptors

Accessing member fields

Typed / Untyped

Access by function / offset

Invoking member functions

Constructing instances

Destroying instances

Records

Customization

Roadmap

License

About

Languages