Немного рефлексии для С++. Часть третья: документационная20.04.2016 10:33

README.cmake
Файл, который рассказывает, как собрать с помощью CMake библиотеку и/или поставляемые вместе с ней дополнительные цели сборки.

/docs
Папка с документацией… Увы, единственное, что в ней сейчас есть — это ссылка на данный цикл статей. Я ошибся, отложил документацию напоследок, и мне не хватило духу заняться ею после трёхнедельной работы без выходных над данным циклом статей.

— Файлы библиотеки cpprt ---
/include
Программный интерфейс для доступа к API библиотеки cpprt.

/src
Папка с исходным кодом библиотеки.

— Сборки для популярных систем ---
/build
Готовые проекты для некоторых популярных тулчейнов и IDE.

/lib
Готовые сборки библиотеки для некоторых популярных компиляторов.

— Дополнительные проекты ---
/examples
Папка с исходным кодом для примеров… В данный момент, для одного простого примера, демонстрирующего принципы использования библиотеки.

/tools
Папка с исходным кодом для тулзов, идущих в поставке с библиотекой.

— Система сборки ---
/build
Пустая папка, в которой рекомендуется выполнять сборку библиотеки и/или дополнительных целей сборки.

CMakeLists.txt
Файл с описанием конфигурации CMake.

— Прочие файлы ---
LICENCE.txt
Файл лицензии, под которой распространяется проект (MIT-лицензия).

copying.txt
Файл с шаблоном шапки для файлов исходного кода, в которой описывается информация о лицензии.

-DBUILD_ALL={OFF/ON}
Если эта опция выставлена в значение ON, то будут сгенерированны конфигурации для всех поставляемых вместе библиотекой сопроводительных проектов. При этом если опции для сборки конкретных целей сборки.

-DBUILD_TOOLS={OFF/ON}
Если данная опция выставлена в значение ON, то будут сгенерированны конфигурации для сборки инструментов, поставляемых вместе с библиотекой. В данный момент есть один инструмент — console (о ней ещё будет дальше).

-DBUILD_EXAMPLES={OFF/ON}
Если данная опция выставлена в значение ON, то будут сгенерированны конфигурации для сборки примеров, поставляемых вместе с библиотекой. В данный момент есть один пример (simple_example) в котором описывается классический для ООП пример иерархии классов животных.

Дополнительные опции:
-DCONSOLE_WITH_EXAMPLE={ON/OFF}
Если данная опция выставлена в ON (по умолчанию выставлена), то вместе с исходным кодом инструмента console будут собраны файлы с описанием тестовых иерархий классов.

// Класс, реализующий общее управление метаданными cpprt.
// Объект-синглтон данного класса используется для большей
// части действий с метаданными классов.
class CPPRTRuntime {
public:

        //----------------------------------------------------------------
        // ТИПЫ

        // Класс, объекты которого хранят метаинформацию
        // для всех регистрируемых классов. Практически не
        // имеет самостоятельного поведения, только аксессоры
        // для доступа к данным. Инициализацией и большей
        // частью действий по регистрации объектов данного
        // класса занимается CPPRTRuntime.
        class ClassData {
        public:

                // Геттеры для получения имени класса.
                // Полное строковое имя класса соответствует
                // записи полного имени в рамках исходного кода
                // С++. Неймспейсы разделяются двумя двоеточиями
                // (ns - сокращение от namespace). Можно условно
                // описать следующим образом отношение между
                // имением и полным именем классов.
                //  = ::::...::
                const char *fullName() const;
                const char *name() const;

                // Геттер, через который можно узнать, является ли
                // класс абстрактным и, соответственно, возможно
                // ли создавать объекты этого класса.
                bool isInterface();

                // Создание объекта класса, которому соответствует
                // данный объект ClassData.
                ICPPRTManagedClass *createObject();
        };

        // Нумератор, с помощью которого конфигурируются
        // особенности получения информации о наследниках класса
        // через метод CPPRTRuntime::observeChildren(…). Флаги задают
        // следующие правила поиска метаданных о наследниках:
        enum ObservingFlag {

                // Если выставлен данный флаг, то в перечень получаемых
                // метаданных не передаются метеданные для абстрактных
                // классов.
                ObservingFlagWithoutInterface = 1 << 0,

                // Данный флаг требует выполнять поиск метаданных
                // для всех наследников рекурсивно (перебор наследников
                // наследников, и далее по древу наследования).
                ObservingFlagRecursive = 1 << 1,

                // Если выставлен данный флаг, то в перечень получаемых
                // метаданных не передаются метаданные класса, для которого
                // выполнялся поиск наследников (аргумент inBaseRegistry
                // метода CPPRTRuntime::observeChildren(…)
                ObservingFlagIgnoreBase = 1 << 2
        };

        // Переменная, через которую передаются флаги при запросе
        // информации о наследовании классов. Флаги передают так,
        // через побитное ИЛИ (общепринятый приём, примеры
        // дальше покажут, как конкретно это работает)
        typedef char ObservingFlags;

        //----------------------------------------------------------------
        // МЕТОДЫ

        // Публичный метод, через который можно получить информацию
        // о наследниках класса inBaseRegistry с учётом правил, которые
        // передаются через флаги inFlags (см. выше). Все найденные метаданные,
        // подходящие по критериям, которые задают флаги, добавляются
        // в массив outRegistries.
        // Если в качестве inBaseRegistry передать NULL, то поиск будет
        // выполняться, условно говоря, начиная с некоего условного
        // класса, от которого наследуются любые регистрированные
        // пользователем классы, не имеющие предков.
        void observeChildren(ClassData *inBaseRegistry,
                        std::vector &outRegistries,
                        ObservingFlags inInheritFlags = 0);

        // Публичный метод для получения метаинформации о классе
        // через его полное строковое имя.
        ClassData *getClassData(const char *inClassName);

        // Публичный метод, позволяющий создать объект по строковому
        // имени его класса.
        ICPPRTManagedClass *createObject(const char *inClassName);
};

// Функция для доступа к глобальному менеджеру метаданных класса.
CPPRTRuntime &cppRuntime();

// Задание синонима типа для хранения метаданных. Пользователю библиотеки
// рекомендуется использовать именно этот синоним в случае, если нужно
// описывать тип данного класса.
typedef CPPRTRuntime::ClassData CPPRTClassData;

// Abstract classes
// Bases
class IWeapon : public ICPPRTManagedClass {
        CPPRT_DECLARATION(IWeapon)
. . .
};

class IAntiAir {
        CPPRT_DECLARATION(IAntiAir)
. . .
};

// Classification by weapon type
class IMachineGunWeapon : public IWeapon {
        CPPRT_DECLARATION(IMachineGunWeapon)
. . .
};

class IRocketWeapon : public IWeapon {
        CPPRT_DECLARATION(IRocketWeapon)
. . .
};

// Concrete classes
// Machine guns
class M16 : public IMachineGunWeapon {
        CPPRT_DECLARATION(M16)
. . .
};

class Abakan : public IMachineGunWeapon {
.       CPPRT_DECLARATION(Abakan)
. . .
};

class Uzi : public IMachineGunWeapon {
        CPPRT_DECLARATION(Uzi)
. . .
};

// Rocket weapons
class Stinger : public IRocketWeapon, public IAntiAir {
        CPPRT_DECLARATION(Stinger)
. . .
};

namespace IraqEdition {
        class Bazuka : public IRocketWeapon {
                CPPRT_DECLARATION(Bazuka)
        . . .
        };
}

// Tank inner classes
class Tank {
public:
        class MachineGunTurret : public Abakan, public IAntiAir {
                CPPRT_DECLARATION(MachineGunTurret)
. . .
        };

        class RocketTurret : public IRocketWeapon {
                CPPRT_DECLARATION(RocketTurret)
. . .
        };
};

// Abstract classes
// Bases
CPPRT_INTERFACE_IMPLEMENTATION_BASE_0(IWeapon)
CPPRT_INTERFACE_IMPLEMENTATION_BASE_0(IAntiAir)

// Classification by weapon type
CPPRT_INTERFACE_IMPLEMENTATION_BASE_1(IMachineGunWeapon, IWeapon)
CPPRT_INTERFACE_IMPLEMENTATION_BASE_1(IRocketWeapon, IWeapon)

// Concrete classes
// Machine guns
CPPRT_CLASS_IMPLEMENTATION_BASE_1(M16, IMachineGunWeapon)
CPPRT_CLASS_IMPLEMENTATION_BASE_1(Abakan, IMachineGunWeapon)
CPPRT_CLASS_IMPLEMENTATION_BASE_1(Uzi, IMachineGunWeapon)

// Rocket weapons
CPPRT_CLASS_IMPLEMENTATION_BASE_2(Stinger, IRocketWeapon, IAntiAir)
CPPRT_CLASS_IMPLEMENTATION_BASE_1(IraqEdition::Bazuka, IRocketWeapon)

// Tank inner classes
CPPRT_CLASS_IMPLEMENTATION_BASE_2(Tank::MachineGunTurret, IRocketWeapon, IAntiAir)

CPPRT_CLASS_IMPLEMENTATION_BASE_1(Tank::RocketTurret, IRocketWeapon)

class Player {
private:
        IWeapon *_weapon; // Set with NULL value in constructor
. . .

public:
        // It’s possible to set player’s weapon by its class name.
        void setWeapon(const char *inName) {
                if (NULL != _weapon) delete _weapon;
                _weapon = cppRuntime().createObject(inName);
        }
. . .
};

int main() {
        Player thePlayer;
        thePlayer1.setWeapon("Abakan");
        return 0;
}

std::vector theParentsData;
cppRuntime().observeParents(TestClass::gClassData, theParentsData,
                ObservingFlagWithoutInterface |
                ObservingFlagRecursive);

CPPRTRuntime::iterator theIterator = cppRuntime().iteratorForClassData(TestClass::gClassData);

// Обход метаданных классов-наследников класса TestClass до тех пор,
// пока не будет найден наследник с именем ClassToFind.
CPPRTRuntime::ClassData *theData = NULL;
while((theData = theIterator.nextChild()) != NULL) {
        if (0 == strcmp(theData->name(), "ClassToFind")) {
                // Если метаданные для класса-наследника с именем найдены – перевести итератор на него
                theIterator.moveToChild();
        }
}

// Classes.cpp

CPPRT_CLASS_IMPLEMENTATION_BASE_1(Car, IVehicle)
CPPRT_CLASS_IMPLEMENTATION_BASE_1(Bus, IVehicle)

CPPRT_CLASS_IMPLEMENTATION_BASE_1(BigBus, IVehicle).
        // Добавление метки "bold_in_editor” для метаданных
        // класса BigBus.
        addTag("bold_in_editor”);

// Using.cpp

// Получение и распечатка метаданных классов, у которых
// выставлена метка "bold_in_editor”
std::vector theChildData;
cppRuntime().observeChildren(TestClass::gClassData, theChildData,
                ObservingFlagWithoutInterface |
                ObservingFlagRecursive |
                ObservingFlagIgnoreBase, "bold_in_editor”);

for (size_t theIndex = 0, theSize = theChildData.size(); theIndex < theSize; ++theIndex) {
        std::cout << theChildData[theIndex]->fullName() << std::endl;
}

cppRuntime().createClassData("MyRTClass”, new CPPRTRuntime::Fabric() );
. . .
// Use registered class
. . .
cppRuntime().removeClassData("MyRTClass”);

Основной проект — это библиотека, позволяющая использовать данные о состоянии объекта, передаваемые для сериализации, с целью генерации метаинформации о данном объекте и дальнейшего использования этой метаинформации.
Замечу, данный подход не нов — его часто используют для игровых проектов, да и некоторые из упомянутых в первой статье аналогов библиотеки cpprt позволяют пользователю задавать подобную информацию для полей классов в момент регистрации классов. Перечислю здесь реализованные и запланированные особенности проекта, из-за которых, на мой взгляд, стоит им заниматься:
1. В библиотеки выполняется не только сбор метаданных о состояниях объектов, но собранные данные также используются для генерации GUI, через которое можно влиять на состояния объектов. За счёт этого пользователю библиотеки достаточно описать методы save и load для объекта, чтобы получить автоматически генерируемый для него GUI object inspector. В данный момент GUI сделан на Qt, но код проектировался с прицелом на поддержку разных GUI (в том числе GUI пользователя, которое можно будет подключить, реализовав интерфейс). В планах до донышка попробовать возможности, открывающиеся за счёт такого взгляда на генерирование GUI.
2. Я всегда фанател от концепции middleware. Меня впечатляла возможность найти общее в ряде инструментов, которые имеют одно назначение, вынести это нечто общее в интерфейс и дальше подсовывать разные инструменты под этот интерфейс, имея возможность выбора реализации интерфейса… Так вот, задумано как следует реализовать концепцию middleware. За счёт этого хочется добиться максимальной простоты интеграции пользователем библиотеки в свой проект, вплоть до передаче системы типов пользователя в шаблонные классы библиотеки.

В данный момент библиотека написана до состояния базового рабочего прототипа, но она требует расширения и углубления функционала, и требует также приведения структуры проекта в публикабельный вид (добавления документации, примеров, тестов, инструментов, и т.д.).

Я надеялся сам пилить эту библиотеку, но в какой-то момент понял, что зашиваюсь… Присоединяйтесь, станете сооснователями проекта. Если вас в какой-нибудь степени заинтересовало всё, что здесь написано — пишите в личку, расскажу подробнее.

Приведём вместе библиотеку в подобающий вид, опубликуем, сделаем цикл статей для пиара… Мало ли — вдруг взлетит, и когда-нибудь мы будем вспоминать, как закладывали вместе начало новой вехи для создания GUI в рамках языка С++?