Scarfski/entt
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

meta: updated documentation

Browse Source
This commit is contained in:
Michele Caini
2019-10-16 13:43:29 +02:00
parent 5a7e954aee
commit 21c6f9e394
3 changed files with 102 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TODO
+1 -1
View File
@@ -36,4 +36,4 @@
* make meta work across boundaries
- extend and make factory::prop more flexible
- doc
- doc (lib.md)
docs/md/meta.md
+98 -77
View File
@@ -46,13 +46,13 @@ identifier is required, it's likely that a user defined literal is used as
follows:
```cpp
auto factory = entt::reflect<my_type>("reflected_type"_hs);
auto factory = entt::meta<my_type>().type("reflected_type"_hs);
```
For what it's worth, this is likely completely equivalent to:
```cpp
auto factory = entt::reflect<my_type>(42);
auto factory = entt::meta<my_type>().type(42);
```
Obviously, human-readable identifiers are more convenient to use and highly
@@ -63,23 +63,33 @@ recommended.
Reflection always starts from real types (users cannot reflect imaginary types
and it would not make much sense, we wouldn't be talking about reflection
anymore).<br/>
To _reflect_ a type, the library provides the `reflect` function:
To create a meta node, the library provides the `meta` function that accepts a
type to reflect as a template parameter:
```cpp
auto factory = entt::reflect<my_type>("reflected_type"_hs);
auto factory = entt::meta<my_type>();
```
It accepts the type to reflect as a template parameter and an optional
identifier as an argument. Identifiers are important because users can retrieve
meta types at runtime by searching for them by _name_. However, there are cases
in which users can be interested in adding features to a reflected type so that
the reflection system can use it correctly under the hood, but they don't want
to allow searching the type by _name_.<br/>
In both cases, the returned value is a factory object to use to continue
building the meta type.
This isn't enough to _export_ the given type and make it visible though.<br/>
The returned value is a factory object to use to continue building the meta
type. In order to make the type _visible_, users can assign it an identifier:
A factory is such that all its member functions returns the factory itself.
It can be used to extend the reflected type and add the following:
```cpp
auto factory = entt::meta<my_type>().type("reflected_type"_hs);
```
When working with named types, it isn't even necessary to specify the
identifier. In fact, it isn't allowed and it will trigger a compilation
error.<br/>
Identifiers are important because users can retrieve meta types at runtime by
searching for them by _name_ other than by type. On the other hand, there are
cases in which users can be interested in adding features to a reflected type so
that the reflection system can use it correctly under the hood, but they don't
want to allow searching the type by _name_. In this case, it's sufficient not
to invoke `type` and the type will not be searchable _by name_.
A factory is such that all its member functions returns the factory itself or
a decorated version of it. This object can be used to add the following:
* _Constructors_. Actual constructors can be assigned to a reflected type by
specifying their list of arguments. Free functions (namely, factories) can be
@@ -89,7 +99,7 @@ It can be used to extend the reflected type and add the following:
Use the `ctor` member function for this purpose:
```cpp
entt::reflect<my_type>("reflected"_hs).ctor<int, char>().ctor<&factory>();
entt::meta<my_type>().ctor<int, char>().ctor<&factory>();
```
* _Destructors_. Free functions can be set as destructors of reflected types.
@@ -98,7 +108,7 @@ It can be used to extend the reflected type and add the following:
Use the `dtor` member function for this purpose:
```cpp
entt::reflect<my_type>("reflected"_hs).dtor<&destroy>();
entt::meta<my_type>().dtor<&destroy>();
```
A function should neither delete nor explicitly invoke the destructor of a
@@ -111,7 +121,7 @@ It can be used to extend the reflected type and add the following:
Use the `data` member function for this purpose:
```cpp
entt::reflect<my_type>("reflected"_hs)
entt::meta<my_type>()
.data<&my_type::static_variable>("static"_hs)
.data<&my_type::data_member>("member"_hs)
.data<&global_variable>("global"_hs);
@@ -132,7 +142,7 @@ It can be used to extend the reflected type and add the following:
Use the `func` member function for this purpose:
```cpp
entt::reflect<my_type>("reflected"_hs)
entt::meta<my_type>()
.func<&my_type::static_function>("static"_hs)
.func<&my_type::member_function>("member"_hs)
.func<&free_function>("free"_hs);
@@ -148,7 +158,7 @@ It can be used to extend the reflected type and add the following:
Use the `base` member function for this purpose:
```cpp
entt::reflect<derived_type>("derived"_hs).base<base_type>();
entt::meta<derived_type>().base<base_type>();
```
From now on, wherever a `base_type` is required, an instance of `derived_type`
@@ -161,7 +171,7 @@ It can be used to extend the reflected type and add the following:
Use the `conv` member function for this purpose:
```cpp
entt::reflect<double>().conv<int>();
entt::meta<double>().conv<int>();
```
That's all, everything users need to create meta types and enjoy the reflection
@@ -173,7 +183,7 @@ definitely worth the price, at least for me.
## Any as in any type
The reflection system comes with its own meta any type. It may seem redundant
The reflection system comes with its own `meta_any` type. It may seem redundant
since C++17 introduced `std::any`, but it is not.<br/>
In fact, the _type_ returned by an `std::any` is a const reference to an
`std::type_info`, an implementation defined class that's not something everyone
@@ -181,26 +191,33 @@ wants to see in a software. Furthermore, the class `std::type_info` suffers from
some design flaws and there is even no way to _convert_ an `std::type_info` into
a meta type, thus linking the two worlds.
A meta any object provides an API similar to that of its most famous counterpart
and serves the same purpose of being an opaque container for any type of
value.<br/>
The class `meta_any` offers an API similar to that of its most famous
counterpart and serves the same purpose of being an opaque container for any
type of value.<br/>
It minimizes the allocations required, which are almost absent thanks to _SBO_
techniques. In fact, unless users deal with _fat types_ and create instances of
them though the reflection system, allocations are at zero.
them through the reflection system, allocations are at zero.
A meta any object can be created by any other object or as an empty container
to initialize later:
Creating instances of `meta_any`, whether empty or from existing objects, is
trivial:
```cpp
// a meta any object that contains an int
// a container for an int
entt::meta_any any{0};
// an empty meta any object
// an empty container
entt::meta_any empty{};
```
It takes the burden of destroying the contained instance when required.<br/>
Moreover, it can be used as an opaque container for unmanaged objects if needed:
The `meta_any` class takes also the burden of destroying the contained object
when required.<br/>
Furthermore, an instance of `meta_any` is not tied to a specific type.
Therefore, the wrapper will be reconfigured by assigning it an object of a
different type than the one contained, so as to be able to handle the new
instance.
A particularly interesting feature of this class is that it can also be used as
an opaque container for unmanaged objects:
```cpp
int value;
@@ -212,10 +229,10 @@ a reference to the original instance rather than making a copy of it. The
contained object is never destroyed and users must ensure that its lifetime
exceeds that of the container.
A meta any object has a `type` member function that returns the meta type of the
contained value, if any. The member functions `try_cast`, `cast` and `convert`
are used to know if the underlying object has a given type as a base or if it
can be converted implicitly to it.
The `meta_any` class has also a `type` member function that returns the meta
type of the contained value, if any. The member functions `try_cast`, `cast` and
`convert` are used to know if the underlying object has a given type as a base
or if it can be converted implicitly to it.
## Enjoy the runtime
@@ -245,10 +262,10 @@ resolve([](auto type) {
});
```
In all cases, the returned value is an instance of `meta_type`. This type of
objects offer an API to know the _runtime identifier_ of the type, to iterate
all the meta objects associated with them and even to build or destroy instances
of the underlying type.<br/>
In all cases, the returned value is an instance of `meta_type`. This kind of
objects offer an API to know their _runtime identifiers_, to iterate all the
meta objects associated with them and even to build or destroy instances of the
underlying type.<br/>
Refer to the inline documentation for all the details.
The meta objects that compose a meta type are accessed in the following ways:
@@ -285,9 +302,9 @@ The meta objects that compose a meta type are accessed in the following ways:
The returned type is `meta_data` and may be invalid if there is no meta data
object associated with the given identifier.<br/>
A meta data object offers an API to query the underlying type (ie to know if
it's a const or a static one), to get the meta type of the variable and to set
or get the contained value.
A meta data object offers an API to query the underlying type (for example, to
know if it's a const or a static one), to get the meta type of the variable
and to set or get the contained value.
* _Meta functions_. They are accessed by _name_:
@@ -297,11 +314,11 @@ The meta objects that compose a meta type are accessed in the following ways:
The returned type is `meta_func` and may be invalid if there is no meta
function object associated with the given identifier.<br/>
A meta function object offers an API to query the underlying type (ie to know
if it's a const or a static function), to know the number of arguments, the
meta return type and the meta types of the parameters. In addition, a meta
function object can be used to invoke the underlying function and then get the
return value in the form of meta any object.
A meta function object offers an API to query the underlying type (for
example, to know if it's a const or a static function), to know the number of
arguments, the meta return type and the meta types of the parameters. In
addition, a meta function object can be used to invoke the underlying function
and then get the return value in the form of a `meta_any` object.
* _Meta bases_. They are accessed through the _name_ of the base types:
@@ -325,16 +342,14 @@ The meta objects that compose a meta type are accessed in the following ways:
conversion function associated with the given type.<br/>
The meta conversion functions are as thin as the meta bases and with a very
similar interface. The sole difference is that they return a newly created
instance wrapped in a meta any object when they convert between different
instance wrapped in a `meta_any` object when they convert between different
types.
All the objects thus obtained as well as the meta types can be explicitly
converted to a boolean value to check if they are valid:
```cpp
auto func = entt::resolve<my_type>().func("member"_hs);
if(func) {
if(auto func = entt::resolve<my_type>().func("member"_hs); func) {
// ...
}
```
@@ -356,7 +371,7 @@ arguments and searches for a match. It returns a `meta_any` object that may or
may not be initialized, depending on whether a suitable constructor has been
found or not. On the other side, the `destroy` member function accepts instances
of `meta_any` as well as actual objects by reference and invokes the registered
destructor if any.<br/>
destructor, if any.<br/>
Be aware that the result of a call to `destroy` may not be what is expected. The
purpose is to give users the ability to free up resources that require special
treatment and **not** to actually destroy instances.
@@ -365,7 +380,7 @@ Meta types and meta objects in general contain much more than what is said: a
plethora of functions in addition to those listed whose purposes and uses go
unfortunately beyond the scope of this document.<br/>
I invite anyone interested in the subject to look at the code, experiment and
read the official documentation to get the best out of this powerful tool.
read the inline documentation to get the best out of this powerful tool.
## Policies: the more, the less
@@ -393,14 +408,12 @@ There are a few alternatives available at the moment:
If the use with functions is obvious, it must be said that it's also possible
to use this policy with constructors and data members. In the first case, the
constructor will be invoked but the returned wrapper will actually be empty.
In the second case, instead, the property will not be accessible for
reading.
In the second case, instead, the property will not be accessible for reading.
As an example of use:
```cpp
entt::reflect<my_type>("reflected"_hs)
.func<&my_type::member_function, entt::as_void_t>("member"_hs);
entt::meta<my_type>().func<&my_type::member_function, entt::as_void_t>("member"_hs);
```
* The _as-alias_ policy, associated with the type `entt::as_alias_t`.<br/>
@@ -415,8 +428,7 @@ There are a few alternatives available at the moment:
As an example of use:
```cpp
entt::reflect<my_type>("reflected"_hs)
.data<&my_type::data_member, entt::as_alias_t>("member"_hs);
entt::meta<my_type>().data<&my_type::data_member, entt::as_alias_t>("member"_hs);
```
Some uses are rather trivial, but it's useful to note that there are some less
@@ -441,11 +453,11 @@ members of the reflected types.
Exporting constant values or elements from an enum is as simple as ever:
```cpp
entt::reflect<my_enum>()
entt::meta<my_enum>()
.data<my_enum::a_value>("a_value"_hs)
.data<my_enum::another_value>("another_value"_hs);
entt::reflect<int>().data<2048>("max_int"_hs);
entt::meta<int>().data<2048>("max_int"_hs);
```
It goes without saying that accessing them is trivial as well. It's a matter of
@@ -457,7 +469,7 @@ auto max = entt::resolve<int>().data("max_int"_hs).get({}).cast<int>();
```
As a side note, remember that all this happens behind the scenes without any
allocation because of the small object optimization performed by the meta any
allocation because of the small object optimization performed by the `meta_any`
class.
## Properties and meta objects
@@ -465,15 +477,26 @@ class.
Sometimes (for example, when it comes to creating an editor) it might be useful
to be able to attach properties to the meta objects created. Fortunately, this
is possible for most of them.<br/>
To attach a property to a meta object, no matter what as long as it supports
properties, it is sufficient to provide an object at the time of construction
such that `std::get<0>` and `std::get<1>` are valid for it. In other terms, the
properties are nothing more than key/value pairs users can put in an
`std::pair`. As an example:
For the meta objects that support properties, the member functions of the
factory used for registering them will return a decorated version of the factory
itself. The latter can be used to attach properties to the last created meta
object.<br/>
Apparently, it's more difficult to say than to do:
```cpp
entt::reflect<my_type>("reflected"_hs, std::make_pair("tooltip"_hs, "message"));
```
entt::meta<my_type>()
.type("reflected_type"_hs)
.prop(entt::hashed_string{"Name"}, "Reflected Type")
.prop("tooltip"_hs, "message")
.prop(my_enum::a_value, 42);
```
Properties are always in the key/value form. There are no restrictions on the
type of the key or value, as long as they are copy constructible objects.<br/>
The meta objects for which properties are supported are currently the meta
types, meta constructors, meta data and meta functions. It's not possible to
attach properties to other types of meta objects and the factory returned as a
result of their construction won't allow such an operation.
The meta objects that support properties offer then a couple of member functions
named `prop` to iterate them at once and to search a specific property by key:
@@ -490,7 +513,7 @@ auto prop = entt::resolve<my_type>().prop("tooltip"_hs);
Meta properties are objects having a fairly poor interface, all in all. They
only provide the `key` and the `value` member functions to be used to retrieve
the key and the value contained in the form of meta any objects, respectively.
the key and the value contained in the form of `meta_any` objects, respectively.
## Unregister types
@@ -499,15 +522,13 @@ means unregistering all its data members, member functions, conversion functions
and so on. However, the base classes won't be unregistered, since they don't
necessarily depend on it. Similarly, implicitly generated types (as an example,
the meta types implicitly generated for function parameters when needed) won't
be unregistered.
To unregister a type, users can use the `unregister` function from the global
namespace:
be unregistered.<br/>
Roughly speaking, unregistering a type means disconnecting all associated meta
objects from it and making its identifier no longer visible. The underlying node
will remain available though, as if it were implicitly generated:
```cpp
entt::unregister<my_type>();
entt::meta<my_type>().reset();
```
This function returns a boolean value that is true if the type is actually
registered with the reflection system, false otherwise.<br/>
The type can be re-registered later with a completely different name and form.
src/entt/meta/factory.hpp
+3
View File
@@ -703,6 +703,9 @@ class extended_meta_factory: public meta_factory<Type> {
public:
/**
* @brief Assigns properties to the last meta object created.
*
* Both the key and the value must be at least copy constructible.
*
* @tparam Key Type of the property key.
* @tparam Value Type of the property value.
* @param pkey Property key.