hana

Boost.Hana

Ihre Standardbibliothek für Metaprogrammierung

Überblick

# 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 ), " " );
}

Dokumentation

Sie können die Dokumentation online unter http://boostorg.github.io/hana durchsuchen. Die Dokumentation deckt alles ab, was Sie benötigen, einschließlich der Installation der Bibliothek, eines Tutorials, das erklärt, was Hana ist und wie man es verwendet, sowie einen ausführlichen Referenzabschnitt mit Beispielen. Der Rest dieser README-Datei richtet sich hauptsächlich an Personen, die an der Bibliothek selbst arbeiten möchten, nicht an deren Benutzer.

Eine Offline-Kopie der Dokumentation erhalten Sie im gh-pages -Zweig. Um ein Überschreiben des aktuellen Verzeichnisses zu vermeiden, können Sie den gh-pages -Zweig in ein Unterverzeichnis wie doc/html klonen:

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

Nach der Ausgabe enthält doc/html genau dieselbe statische Website, die online verfügbar ist. Beachten Sie, dass doc/html von Git automatisch ignoriert wird, sodass die Aktualisierung der Dokumentation Ihren Index nicht verunreinigt.

Hacking auf Hana

Es ist einfach, sich auf die Arbeit mit Hana vorzubereiten. Zunächst benötigen Sie eine Installation von CMake. Sobald dies erledigt ist, können Sie zum Stammverzeichnis des Projekts cd und das Build-Verzeichnis einrichten:

mkdir build
cmake -S . -B build

Manchmal möchten Sie einen benutzerdefinierten Compiler angeben, weil der Compiler des Systems zu alt ist:

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

Normalerweise funktioniert das ganz gut. Auf einigen älteren Systemen unterstützen die standardmäßig bereitgestellte Standardbibliothek und/oder der standardmäßig bereitgestellte Compiler C++14 jedoch nicht. Wenn dies bei Ihnen der Fall ist, finden Sie im Wiki weitere Informationen zum Einrichten auf verschiedenen Systemen.

Normalerweise versucht Hana, Boost-Header zu finden, sofern Sie diese auf Ihrem System haben. Es ist auch in Ordnung, wenn Sie sie nicht haben; Einige Tests, die die Boost-Header erfordern, werden in diesem Fall deaktiviert. Wenn Sie jedoch möchten, dass Hana eine benutzerdefinierte Installation von Boost verwendet, können Sie den Pfad zu dieser benutzerdefinierten Installation angeben:

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

Sie können jetzt die Komponententests und Beispiele erstellen und ausführen:

cmake --build build --target check

Sie sollten sich darüber im Klaren sein, dass das Kompilieren der Unit-Tests ziemlich zeit- und speicherintensiv ist, insbesondere die Tests für externe Adapter. Dies liegt an der Tatsache, dass Hanas Unit-Tests sehr gründlich sind, und auch daran, dass heterogene Sequenzen in anderen Bibliotheken tendenziell eine schreckliche Leistung bei der Kompilierung aufweisen.

Es gibt auch optionale Ziele, die nur aktiviert werden, wenn die erforderliche Software auf Ihrem Computer verfügbar ist. Zum Generieren der Dokumentation ist beispielsweise die Installation von Doxygen erforderlich. Während des CMake-Generierungsschritts wird immer dann eine informative Meldung gedruckt, wenn ein optionales Ziel deaktiviert wird. Sie können fehlende Software installieren und dann die CMake-Generierung erneut ausführen, um die Liste der verfügbaren Ziele zu aktualisieren.

Tipp

Über das help können Sie eine Liste aller verfügbaren Ziele abrufen.

Wenn Sie Unit-Tests oder Beispiele hinzufügen möchten, fügen Sie einfach eine Quelldatei in test/ oder example/ hinzu und führen Sie dann den CMake-Generierungsschritt erneut aus, damit die neue Quelldatei dem Build-System bekannt ist. Nehmen wir an, der relative Pfad vom Stammverzeichnis des Projekts zur neuen Quelldatei ist path/to/file.cpp . Wenn Sie den CMake-Generierungsschritt erneut ausführen, wird ein neues Ziel mit dem Namen path.to.file erstellt und ein Test mit demselben Namen wird ebenfalls erstellt. Somit,

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 

Tipp für Benutzer von Sublime Text

Wenn Sie die bereitgestellte hana.sublime-project-Datei verwenden, können Sie das Build-System „[Hana] Aktuelle Datei erstellen“ auswählen. Wenn Sie eine Datei anzeigen, mit der ein Ziel verknüpft ist (z. B. ein Test oder ein Beispiel), können Sie diese dann kompilieren, indem Sie ⌘B drücken, oder sie kompilieren und dann mit ⇧⌘B ausführen.

Projektorganisation

Das Projekt ist in mehreren Unterverzeichnissen organisiert.

• Das Benchmark-Verzeichnis enthält Kompilierzeit- und Laufzeit-Benchmarks, um sicherzustellen, dass die Bibliothek so schnell ist wie angekündigt. Der Benchmark-Code wird größtenteils in Form von eRuby-Vorlagen geschrieben. Die Vorlagen werden zum Generieren von C++-Dateien verwendet, die dann kompiliert werden, während gleichzeitig Kompilierungs- und Ausführungsstatistiken erfasst werden.
• Das cmake-Verzeichnis enthält verschiedene CMake-Module und andere Skripte, die vom Build-System benötigt werden.
• Das doc-Verzeichnis enthält Konfigurationsdateien, die zum Generieren der Dokumentation erforderlich sind. Das Unterverzeichnis doc/html wird von Git automatisch ignoriert; Sie können bequem eine lokale Kopie der Dokumentation speichern, indem Sie den Zweig gh-pages in dieses Verzeichnis klonen, wie oben erläutert.
• Das Beispielverzeichnis enthält den Quellcode für alle Beispiele sowohl des Tutorials als auch der Referenzdokumentation.
• Das Include-Verzeichnis enthält die Bibliothek selbst, bei der es sich nur um den Header handelt.
• Das Testverzeichnis enthält den Quellcode für alle Unit-Tests.

Mitwirken

Bitte sehen Sie sich CONTRIBUTING.md an.

Lizenz

Bitte sehen Sie sich LICENSE.md an.

Loslassen

Die Veröffentlichung erfolgt nun ausschließlich über den Boost-Release-Prozess. Es gibt keine separaten Versionen von Hana, da die Bibliothek mittlerweile ziemlich stabil ist.