hana

Boost.Hana

Votre bibliothèque standard pour la métaprogrammation

Aperçu

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

Documentation

Vous pouvez parcourir la documentation en ligne sur http://boostorg.github.io/hana. La documentation couvre tout ce dont vous avez besoin, y compris l'installation de la bibliothèque, un didacticiel expliquant ce qu'est Hana et comment l'utiliser, ainsi qu'une section de référence complète avec des exemples. Le reste de ce README est principalement destiné aux personnes souhaitant travailler sur la bibliothèque elle-même, et non à ses utilisateurs.

Une copie hors ligne de la documentation peut être obtenue en consultant la branche gh-pages . Pour éviter d'écraser le répertoire courant, vous pouvez cloner la branche gh-pages dans un sous-répertoire comme doc/html :

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

Après avoir émis ceci, doc/html contiendra exactement le même site Web statique disponible en ligne. Notez que doc/html est automatiquement ignoré par Git, donc la mise à jour de la documentation ne polluera pas votre index.

Piratage sur Hana

Se préparer à travailler sur Hana est facile. Tout d’abord, vous aurez besoin d’une installation de CMake. Une fois cela fait, vous pouvez cd à la racine du projet et configurer le répertoire de construction :

mkdir build
cmake -S . -B build

Parfois, vous souhaiterez spécifier un compilateur personnalisé car le compilateur du système est trop ancien :

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

Habituellement, cela fonctionnera très bien. Cependant, sur certains systèmes plus anciens, la bibliothèque standard et/ou le compilateur fourni par défaut ne prend pas en charge C++14. Si tel est votre cas, le wiki contient plus d'informations sur votre configuration sur différents systèmes.

Normalement, Hana essaie de trouver les en-têtes Boost si vous les avez sur votre système. C'est également bien si vous ne les avez pas ; quelques tests nécessitant les en-têtes Boost seront désactivés dans ce cas. Cependant, si vous souhaitez qu'Hana utilise une installation personnalisée de Boost, vous pouvez spécifier le chemin d'accès à cette installation personnalisée :

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

Vous pouvez maintenant créer et exécuter les tests unitaires et les exemples :

cmake --build build --target check

Vous devez être conscient que la compilation des tests unitaires prend beaucoup de temps et de RAM, en particulier les tests des adaptateurs externes. Cela est dû au fait que les tests unitaires de Hana sont très approfondis et également au fait que les séquences hétérogènes dans d'autres bibliothèques ont tendance à avoir d'horribles performances au moment de la compilation.

Il existe également des cibles facultatives qui ne sont activées que lorsque le logiciel requis est disponible sur votre ordinateur. Par exemple, la génération de la documentation nécessite l'installation de Doxygen. Un message informatif sera imprimé lors de l'étape de génération CMake chaque fois qu'une cible facultative est désactivée. Vous pouvez installer tout logiciel manquant, puis réexécuter la génération CMake pour mettre à jour la liste des cibles disponibles.

Conseil

Vous pouvez utiliser la cible help pour obtenir une liste de toutes les cibles disponibles.

Si vous souhaitez ajouter des tests unitaires ou des exemples, ajoutez simplement un fichier source dans test/ ou example/ puis réexécutez l'étape de génération CMake afin que le nouveau fichier source soit connu du système de build. Supposons que le chemin relatif de la racine du projet au nouveau fichier source soit path/to/file.cpp . Lorsque vous réexécutez l'étape de génération CMake, une nouvelle cible nommée path.to.file sera créée et un test du même nom sera également créé. Ainsi,

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 

Astuce pour les utilisateurs de Sublime Text

Si vous utilisez le fichier hana.sublime-project fourni, vous pouvez sélectionner le système de construction "[Hana] Build current file". Lors de la visualisation d'un fichier auquel une cible est associée (comme un test ou un exemple), vous pouvez ensuite le compiler en appuyant sur ⌘B, ou le compiler puis l'exécuter en utilisant ⇧⌘B.

Organisation du projet

Le projet est organisé en quelques sous-répertoires.

• Le répertoire de référence contient des références de compilation et d'exécution pour garantir que la bibliothèque est aussi rapide qu'annoncé. Le code de référence est écrit principalement sous la forme de modèles eRuby. Les modèles sont utilisés pour générer des fichiers C++ qui sont ensuite compilés tout en collectant des statistiques de compilation et d'exécution.
• Le répertoire cmake contient divers modules CMake et autres scripts nécessaires au système de build.
• Le répertoire doc contient les fichiers de configuration nécessaires pour générer la documentation. Le sous-répertoire doc/html est automatiquement ignoré par Git ; vous pouvez facilement stocker une copie locale de la documentation en clonant la branche gh-pages dans ce répertoire, comme expliqué ci-dessus.
• Le répertoire d'exemples contient le code source de tous les exemples du didacticiel et de la documentation de référence.
• Le répertoire include contient la bibliothèque elle-même, qui n'est qu'un en-tête.
• Le répertoire test contient le code source de tous les tests unitaires.

Contribuer

Veuillez consulter CONTRIBUTING.md.

Licence

Veuillez consulter LICENSE.md.

Libération

La publication se fait désormais exclusivement via le processus de publication Boost. Il n'existe pas de version distincte de Hana puisque la bibliothèque est désormais assez stable.