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

1. Про разработку
2. Про подготовку к публикации
3. Про результат

— Документация ---
readme.md
Ридми-файл. Задумывался как файл, c которого начинается ознакомление с проектом.

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

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

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

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

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

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

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

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

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

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

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

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

Независимо от выбранных опций, в сгенерированных конфигах (файлах IDE) всегда будет по крайней мере одна цель сборки — для статической сборки самой библиотеки cpprt. Для того, чтобы сгенерировать конфиги для сборки дополнительно сопроводительных проектов, вы можете использовать следующие опции (первой указывается значение опции по-умолчанию):

-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). Можно условно
		// описать следующим образом отношение между
		// имением и полным именем классов.
		// <fullName> = <ns>::<ns>::<ns>...<ns>::<name>
		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<ClassData *> &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<ClassData *> 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<ClassData *> 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<MyRTClass>() );
. . .
// Use registered class
. . .
cppRuntime().removeClassData(“MyRTClass”);

Значит, интересно, что за «основной проект»?.. Если вы это читаете — значит план удался.

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

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

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

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

Редактирование статьи: Сергей Семенякин