hana

Boost.Хана

Ваша стандартная библиотека для метапрограммирования

Обзор

# include < boost/hana.hpp >
# include < cassert >
# include < string >
namespace hana = boost::hana;
using namespace hana ::literals ;

struct Fish { std::string name; };
struct Cat  { std::string name; };
struct Dog  { std::string name; };

int main () {
  // Sequences capable of holding heterogeneous objects, and algorithms
  // to manipulate them.
  auto animals = hana::make_tuple (Fish{ " Nemo " }, Cat{ " Garfield " }, Dog{ " Snoopy " });
  auto names = hana::transform (animals, []( auto a) {
    return a. name ;
  });
  assert ( hana::reverse (names) == hana::make_tuple ( " Snoopy " , " Garfield " , " Nemo " ));

  // No compile-time information is lost: even if `animals` can't be a
  // constant expression because it contains strings, its length is constexpr.
  static_assert ( hana::length (animals) == 3u , " " );

  // Computations on types can be performed with the same syntax as that of
  // normal C++. Believe it or not, everything is done at compile-time.
  auto animal_types = hana::make_tuple (hana::type_c<Fish*>, hana::type_c<Cat&>, hana::type_c<Dog*>);
  auto animal_ptrs = hana::filter (animal_types, []( auto a) {
    return hana::traits::is_pointer (a);
  });
  static_assert (animal_ptrs == hana::make_tuple (hana::type_c<Fish*>, hana::type_c<Dog*>), " " );

  // And many other goodies to make your life easier, including:
  // 1. Access to elements in a tuple with a sane syntax.
  static_assert (animal_ptrs[0_c] == hana::type_c<Fish*>, " " );
  static_assert (animal_ptrs[1_c] == hana::type_c<Dog*>, " " );

  // 2. Unroll loops at compile-time without hassle.
  std::string s;
  hana::int_c< 10 >. times ([&]{ s += " x " ; });
  // equivalent to s += "x"; s += "x"; ... s += "x";

  // 3. Easily check whether an expression is valid.
  //    This is usually achieved with complex SFINAE-based tricks.
  auto has_name = hana::is_valid ([]( auto && x) -> decltype (( void )x. name ) { });
  static_assert ( has_name (animals[0_c]), " " );
  static_assert (! has_name ( 1 ), " " );
}

Документация

Вы можете просмотреть документацию онлайн по адресу http://boostorg.github.io/hana. Документация охватывает все, что вам может понадобиться, включая установку библиотеки, руководство, объясняющее, что такое Hana и как ее использовать, а также обширный справочный раздел с примерами. Оставшаяся часть этого README предназначена в основном для людей, желающих работать с самой библиотекой, а не для ее пользователей.

Автономную копию документации можно получить, посетив ветку gh-pages . Чтобы избежать перезаписи текущего каталога, вы можете клонировать ветку gh-pages в подкаталог, например doc/html :

git clone http://github.com/boostorg/hana --branch=gh-pages --depth=1 doc/html

После этого документ doc/html будет содержать точно такой же статический веб-сайт, который доступен в Интернете. Обратите внимание, что doc/html автоматически игнорируется Git, поэтому обновление документации не загрязнит ваш индекс.

Взлом Ханы

Настроить себя на работу над Ханой легко. Во-первых, вам понадобится установка CMake. Как только это будет сделано, вы можете cd в корень проекта и настроить каталог сборки:

mkdir build
cmake -S . -B build

Иногда вам нужно указать собственный компилятор, потому что системный компилятор слишком старый:

cmake -S . -B build -DCMAKE_CXX_COMPILER=/path/to/compiler

Обычно это работает нормально. Однако в некоторых старых системах стандартная библиотека и/или компилятор, предоставляемые по умолчанию, не поддерживают C++14. Если это ваш случай, в вики есть дополнительная информация о настройке в разных системах.

Обычно Хана пытается найти заголовки Boost, если они есть в вашей системе. Также хорошо, если у вас их нет; в этом случае несколько тестов, требующих заголовков Boost, будут отключены. Однако если вы хотите, чтобы Hana использовала выборочную установку Boost, вы можете указать путь к этой выборочной установке:

cmake -S . -B build -DCMAKE_CXX_COMPILER=/path/to/compiler -DBOOST_ROOT=/path/to/boost

Теперь вы можете создавать и запускать модульные тесты и примеры:

cmake --build build --target check

Вы должны знать, что компиляция модульных тестов занимает довольно много времени и требует много оперативной памяти, особенно тестов для внешних адаптеров. Это связано с тем, что модульные тесты Hana очень тщательны, а также с тем, что гетерогенные последовательности в других библиотеках имеют ужасную производительность во время компиляции.

Существуют также дополнительные цели, которые активируются только тогда, когда необходимое программное обеспечение доступно на вашем компьютере. Например, для создания документации требуется установка Doxygen. Информационное сообщение будет печататься на этапе создания CMake всякий раз, когда необязательная цель отключена. Вы можете установить любое недостающее программное обеспечение, а затем повторно запустить создание CMake, чтобы обновить список доступных целевых объектов.

Кончик

Вы можете использовать цель help , чтобы получить список всех доступных целей.

Если вы хотите добавить модульные тесты или примеры, просто добавьте исходный файл в test/ или example/ а затем повторно запустите этап создания CMake, чтобы новый исходный файл был известен системе сборки. Предположим, относительный путь от корня проекта до нового исходного файла — path/to/file.cpp . При повторном запуске этапа создания CMake будет создана новая цель с именем path.to.file , а также будет создан тест с тем же именем. Следовательно,

cmake --build build --target path.to.file # Builds the program associated to path/to/file.cpp
ctest --test-dir build -R path.to.file # Runs the program as a test 

Совет для пользователей Sublime Text

Если вы используете предоставленный файл проекта hana.sublime-project, вы можете выбрать систему сборки «[Hana] Создать текущий файл». При просмотре файла, с которым связана цель (например, тест или пример), вы можете затем скомпилировать его, нажав ⌘B, или скомпилировать и затем запустить его, используя ⇧⌘B.

Организация проекта

Проект организован в нескольких подкаталогах.

• Каталог тестов содержит тесты времени компиляции и выполнения, позволяющие убедиться, что библиотека работает так же быстро, как заявлено. Код теста производительности написан в основном в виде шаблонов eRuby. Шаблоны используются для создания файлов C++, которые затем компилируются при сборе статистики компиляции и выполнения.
• Каталог cmake содержит различные модули CMake и другие скрипты, необходимые системе сборки.
• Каталог doc содержит файлы конфигурации, необходимые для создания документации. Подкаталог doc/html автоматически игнорируется Git; вы можете удобно хранить локальную копию документации, клонировав ветку gh-pages в этот каталог, как описано выше.
• Каталог примеров содержит исходный код для всех примеров как учебного пособия, так и справочной документации.
• Каталог включения содержит саму библиотеку, которая представляет собой только заголовок.
• Каталог тестов содержит исходный код для всех модульных тестов.

Содействие

Пожалуйста, посетите CONTRIBUTING.md.

Лицензия

Пожалуйста, посетите LICENSE.md.

Выпуск

Выпуск теперь осуществляется исключительно через процесс выпуска Boost. Отдельных выпусков Hana не существует, поскольку библиотека сейчас довольно стабильна.