Repository files navigation

Your standard library for metaprogramming

#include<boost/hana.hpp>#include<cassert>#include<string>namespacehana= boost::hana;usingnamespacehana::literals;structFish { std::string name; };structCat  { std::string name; };structDog  { std::string name; };intmain() {// 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) {returnhana::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),"");}

You can browse the documentation online athttp://boostorg.github.io/hana.The documentation covers everything you should need including installing thelibrary, a tutorial explaining what Hana is and how to use it, and an extensivereference section with examples. The remainder of this README is mostly forpeople that wish to work on the library itself, not for its users.

An offline copy of the documentation can be obtained by checking out thegh-pages branch. To avoid overwriting the current directory, you can clonethegh-pages branch into a subdirectory likedoc/html:

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

After issuing this,doc/html will contain exactly the same static websitethat isavailable online. Note thatdoc/html is automaticallyignored by Git so updating the documentation won't pollute your index.

Setting yourself up to work on Hana is easy. First, you will need aninstallation ofCMake. Once this is done, you cancd to the rootof the project and setup the build directory:

mkdir buildcd buildcmake ..

Usually, you'll want to specify a custom compiler because the system'scompiler is too old:

cmake .. -DCMAKE_CXX_COMPILER=/path/to/compiler

Usually, this will work just fine. However, on some systems, the standardlibrary and/or compiler provided by default does not support C++14. Ifthis is your case, thewiki has more information aboutsetting you up on different systems.

Normally, Hana tries to find Boost headers if you have them on your system.It's also fine if you don't have them; a few tests requiring the Boost headerswill be disabled in that case. However, if you'd like Hana to use a custominstallation of Boost, you can specify the path to this custom installation:

cmake .. -DCMAKE_CXX_COMPILER=/path/to/compiler -DBOOST_ROOT=/path/to/boost

You can now build and run the unit tests and the examples:

cmake --build. --target check

You should be aware that compiling the unit tests is pretty time and RAMconsuming, especially the tests for external adapters. This is due to thefact that Hana's unit tests are very thorough, and also that heterogeneoussequences in other libraries tend to have horrible compile-time performance.

There are also optional targets which are enabled only when the requiredsoftware is available on your computer. For example, generating thedocumentation requiresDoxygen to be installed. An informative messagewill be printed during the CMake generation step whenever an optional targetis disabled. You can install any missing software and then re-run the CMakegeneration to update the list of available targets.

Tip

You can use thehelp target to get a list of all the available targets.

If you want to add unit tests or examples, just add a source file intest/orexample/ and then re-run the CMake generation step so the new sourcefile is known to the build system. Let's suppose the relative path from theroot of the project to the new source file ispath/to/file.cpp. When youre-run the CMake generation step, a new target namedpath.to.file will becreated, and a test of the same name will also be created. Hence,

cd build# Go back to the build directorycmake --build. --target path.to.file# Builds the program associated to path/to/file.cppctest -R path.to.file# Runs the program as a test

Tip for Sublime Text users

If you use the providedhana.sublime-project file,you can select the "[Hana] Build current file" build system. When viewing afile to which a target is associated (like a test or an example), you canthen compile it by pressing ⌘B, or compile and then run it using ⇧⌘B.

The project is organized in a couple of subdirectories.

• Thebenchmark directory contains compile-time and runtimebenchmarks to make sure the library is as fast as advertised. The benchmarkcode is written mostly in the form ofeRuby templates. The templatesare used to generate C++ files which are then compiled while gatheringcompilation and execution statistics.
• Thecmake directory contains various CMake modules and otherscripts needed by the build system.
• Thedoc directory contains configuration files needed to generatethe documentation. Thedoc/html subdirectory is automatically ignoredby Git; you can conveniently store a local copy of the documentation bycloning thegh-pages branch into that directory, as explained above.
• Theexample directory contains the source code for all theexamples of both the tutorial and the reference documentation.
• Theinclude directory contains the library itself, which isheader only.
• Thetest directory contains the source code for all the unit tests.

Please seeCONTRIBUTING.md.

Please seeLICENSE.md.

To release a new version of Hana, use theutil/release.sh script. The scriptwill mergedevelop tomaster, create a tag onmaster and then bump theversion ondevelop. The tag onmaster will be annotated with the contentsof theRELEASE_NOTES.md file. Once therelease.sh script has been run, themaster anddevelop branches should be pushed manually, as well as the tagthat was created onmaster. Finally, create a GitHub release pointing to thenew tag onmaster.