Mirror C++ reflection library

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)

Note:: Although Mirror uses the Boost C++ libraries Coding Guidelines and is implemented inside of the boost namespace, it IS NOT an officially reviewed and accepted Boost library. Mirror is being developed with the intention to be submitted for review for inclusion to the Boost C++ libraries.; The Mirror library is currently in development and so is this documentation.

This manual is divided into the following sections:

The aim of the Mirror library is to provide both compile-time and run-time meta-data describing common C++ constructs like namespaces, types (and as an important special case typedef-ined types), classes and their base classes and member variables, constructors, etc. and to provide uniform and generic interfaces for their introspection.

Because standard C++ provides only a very limited set of meta-information to build upon, the main drawback of this library is, that namespace, types, classes, etc. need to be registered before they can be reflected. However Mirror tries to make the process of registering simple by providing a set of user-friendly registering macros and has the native and many of the other common types, classes, templates and namespaces pre-registered.

Furthermore several tools for automatic / semi-automatic registering are being worked on.

Once registered the meta-data can be reused in a large number of situations.

Mirror is designed with the principle of stratification in mind and tries to be as less intrusive as possible. New or existing classes do not need to be designed to directly support Mirror and no Mirror-related code is necessary in the class' definition, as far as some general guidelines are followed.

Mirror provides a compile-time reflection layer which can be used in compile-time meta-programs and a run-time layer with a similar, but dynamic interface based on the compile-time meta-data.

Features

Static and dynamic reflection of the following base-level language constructs:
- namespaces [static / dynamic ]
- types [static / dynamic ]
- typedefs [static ]
- classes [static / dynamic ]
- class templates [static ]

Static and dynamic range based traversals of:
- namespace members like nested namespaces, classes, typedefs, templates, etc. [static / dynamic ]
- class inheritance including the inheritance type specifier, access specifier, the derived and the base class in the inheritance [static / dynamic ]
- class member variables providing information about the storage class specifier, access specifier, scope, type and name of the member variable [static / dynamic ]
- all class member variables including those inherited from base classes [static / dynamic ]
- class member functions static / dynamic ]
- constructors [static / dynamic ]
- conversion operators [static / dynamic ]
- template parameters [static / dynamic ]
- function parameters including the type and the name of the parameter [static / dynamic ]

The factory generator utility

Other compile-time meta-programming utilities

Name getter functions for all named language constructs like namespaces, types (including derived types like pointers, references, arrays, functions, CV-qualified types and combinations thereof), typedefs, member variables, etc.
- base names without the nested name specifiers [static / dynamic ]
- full names with the nested name specifiers [static / dynamic ]
- local names of nested named constructs which can have parts of the full nested name specifier stripped away based on the use of the Mirror's using directive on the global scope or the local scopes [static / dynamic ]
- generic name getter allowing to choose the character type of the returned string

Generic functions for getting and setting the value of a class member variable when given a reference to the class to which the member variable belongs.

Meta-object reflection , categorization and tag dispatching. Tag types for different meta-objects can be used in compile-time function overload or template specialization dispatching and meta-object tag enumerations in run-time branching based on the type of the meta-object.

Higher-level utilities based on the basic meta-data:
- Factory generators allowing to easily create highly customizable, specialized factory classes which gather the necessary parameter values, pick and call the appropriate constructor in a user specified way (from a GUI, from a RDB dataset, from an XML file, etc.) to create instances of a specified type.

Annotation of meta-objects with tag types. Various meta objects (currently only types) can be tagged by pre-defined or application-specific tag types which can be used in meta-programs for the triggering of specialized processing.

Planned features

Higher-level utilities based on the basic meta-data:
- Object inspectors similar to the factory generators utility, which would allow to build classes for inspection of the structure (and values where applicable) of a class, type, namespace, member variable etc. in a user-defined way (in a GUI for example).
- Traversals of namespaces, classes, etc for (de)serialization-like operations.
- Access to semantic data describing the individual language constructs conceptually. This would allow for example to write agents able to use objects of other applications without access to their sources defining these classes.

Automatic (or semi-automatic) registering, using various common tools and toolchains like (doxygen, gcc2xml, openc++, xslt, etc.) or specialized portable parsers and transformers for generating the source code necessary for registering the base-level constructs with Mirror.
- May be fully automatic in some cases
- May use annotations embedded in comments (like doxygen does)

Download

Packaged releases

The current and the previous releases of the packaged sources can be downloaded from Sourceforge at the following url: http://sourceforge.net/projects/mirror-lib/files/, or from the Boost Vault [www.boostpro.com] by using this download link.

Subversion repository

Subversion users can get anonymous read-only access to the source repository. To access the current development code one would check out from the main trunk (located at https://mirror-lib.svn.sourceforge.net/svnroot/mirror-lib/trunk) using the following svn command:

svn co https://mirror-lib.svn.sourceforge.net/svnroot/mirror-lib/trunk mirror-trunk

To check out the whole repository including the branches and tags one might do:

svn co https://mirror-lib.svn.sourceforge.net/svnroot/mirror-lib mirror

Previous version

The previous (non C++1x) version of Mirror can be downloaded from the Boost Vault (direct link [www.boostpro.com]) or checked out from the Boost Sandbox subversion repository at the following url: http://svn.boost.org/svn/boost/sandbox/mirror/ the documentation for this version is located here [svn.boost.org].

Getting started

Building with Mirror

Mirror is a header-only library which means that you don't need build nor link to any separate library to use it. All that is needed to use Mirror is to include the $MIRROR_ROOT/mirror.hpp header. To use Mirror without the pre-registered namespaces, types, classes, templates, include the $MIRROR_ROOT/mirror_no_prereg.hpp header.

Requirements

Mirror currently does not have any external dependencies besides the (C++1x) standard library (with the exception of several tools listed below, which are however, not required for the use of the main features of the library).

wxWidgets-based factory generator template which can be used together with the factory generator utility to create GUI dialogs for the input of parameters necessary for the construction of instances of various types (requires wxWidgets [www.wxwidgets.org])

Supported compilers

The Mirror library is currently known to work with the following compilers:

GNU C++ [gcc.gnu.org] 4.5.0 and higher

Mirror does not use any compiler-specific extensions and should be usable with any C++1x ready compiler.

History

This version of the Mirror library is a major rewrite of a previous version which has been developed in C++98 since April 2008 (available in the Boost Sandbox [svn.boost.org]).

The new (C++1x) version draws from more than one and half year of user experience with the previous version and is in development since September 2009.