1# Boost.Hana <a target="_blank" href="http://semver.org">![Version][badge.version]</a> <a target="_blank" href="https://travis-ci.org/boostorg/hana">![Travis status][badge.Travis]</a> <a target="_blank" href="https://ci.appveyor.com/project/ldionne/hana">![Appveyor status][badge.Appveyor]</a> <a target="_blank" href="http://melpon.org/wandbox/permlink/g4ozIK33ITDtyGa3">![Try it online][badge.wandbox]</a> <a target="_blank" href="https://gitter.im/boostorg/hana">![Gitter Chat][badge.Gitter]</a> 2 3> Your standard library for metaprogramming 4 5## Overview 6<!-- Important: keep this in sync with example/overview.cpp --> 7```cpp 8#include <boost/hana.hpp> 9#include <cassert> 10#include <string> 11namespace hana = boost::hana; 12using namespace hana::literals; 13 14struct Fish { std::string name; }; 15struct Cat { std::string name; }; 16struct Dog { std::string name; }; 17 18int main() { 19 // Sequences capable of holding heterogeneous objects, and algorithms 20 // to manipulate them. 21 auto animals = hana::make_tuple(Fish{"Nemo"}, Cat{"Garfield"}, Dog{"Snoopy"}); 22 auto names = hana::transform(animals, [](auto a) { 23 return a.name; 24 }); 25 assert(hana::reverse(names) == hana::make_tuple("Snoopy", "Garfield", "Nemo")); 26 27 // No compile-time information is lost: even if `animals` can't be a 28 // constant expression because it contains strings, its length is constexpr. 29 static_assert(hana::length(animals) == 3u, ""); 30 31 // Computations on types can be performed with the same syntax as that of 32 // normal C++. Believe it or not, everything is done at compile-time. 33 auto animal_types = hana::make_tuple(hana::type_c<Fish*>, hana::type_c<Cat&>, hana::type_c<Dog*>); 34 auto animal_ptrs = hana::filter(animal_types, [](auto a) { 35 return hana::traits::is_pointer(a); 36 }); 37 static_assert(animal_ptrs == hana::make_tuple(hana::type_c<Fish*>, hana::type_c<Dog*>), ""); 38 39 // And many other goodies to make your life easier, including: 40 // 1. Access to elements in a tuple with a sane syntax. 41 static_assert(animal_ptrs[0_c] == hana::type_c<Fish*>, ""); 42 static_assert(animal_ptrs[1_c] == hana::type_c<Dog*>, ""); 43 44 // 2. Unroll loops at compile-time without hassle. 45 std::string s; 46 hana::int_c<10>.times([&]{ s += "x"; }); 47 // equivalent to s += "x"; s += "x"; ... s += "x"; 48 49 // 3. Easily check whether an expression is valid. 50 // This is usually achieved with complex SFINAE-based tricks. 51 auto has_name = hana::is_valid([](auto&& x) -> decltype((void)x.name) { }); 52 static_assert(has_name(animals[0_c]), ""); 53 static_assert(!has_name(1), ""); 54} 55``` 56 57 58## Documentation 59You can browse the documentation online at http://boostorg.github.io/hana. 60The documentation covers everything you should need including installing the 61library, a tutorial explaining what Hana is and how to use it, and an extensive 62reference section with examples. The remainder of this README is mostly for 63people that wish to work on the library itself, not for its users. 64 65An offline copy of the documentation can be obtained by checking out the 66`gh-pages` branch. To avoid overwriting the current directory, you can clone 67the `gh-pages` branch into a subdirectory like `doc/html`: 68```shell 69git clone http://github.com/boostorg/hana --branch=gh-pages --depth=1 doc/html 70``` 71 72After issuing this, `doc/html` will contain exactly the same static website 73that is [available online][Hana.docs]. Note that `doc/html` is automatically 74ignored by Git so updating the documentation won't pollute your index. 75 76 77## Hacking on Hana 78Setting yourself up to work on Hana is easy. First, you will need an 79installation of [CMake][]. Once this is done, you can `cd` to the root 80of the project and setup the build directory: 81```shell 82mkdir build 83cd build 84cmake .. 85``` 86 87Usually, you'll want to specify a custom compiler because the system's 88compiler is too old: 89```shell 90cmake .. -DCMAKE_CXX_COMPILER=/path/to/compiler 91``` 92 93Usually, this will work just fine. However, on some systems, the standard 94library and/or compiler provided by default does not support C++14. If 95this is your case, the [wiki][Hana.wiki] has more information about 96setting you up on different systems. 97 98Normally, Hana tries to find Boost headers if you have them on your system. 99It's also fine if you don't have them; a few tests requiring the Boost headers 100will be disabled in that case. However, if you'd like Hana to use a custom 101installation of Boost, you can specify the path to this custom installation: 102```shell 103cmake .. -DCMAKE_CXX_COMPILER=/path/to/compiler -DBOOST_ROOT=/path/to/boost 104``` 105 106You can now build and run the unit tests and the examples: 107```shell 108cmake --build . --target check 109``` 110 111You should be aware that compiling the unit tests is pretty time and RAM 112consuming, especially the tests for external adapters. This is due to the 113fact that Hana's unit tests are very thorough, and also that heterogeneous 114sequences in other libraries tend to have horrible compile-time performance. 115 116There are also optional targets which are enabled only when the required 117software is available on your computer. For example, generating the 118documentation requires [Doxygen][] to be installed. An informative message 119will be printed during the CMake generation step whenever an optional target 120is disabled. You can install any missing software and then re-run the CMake 121generation to update the list of available targets. 122 123> #### Tip 124> You can use the `help` target to get a list of all the available targets. 125 126If you want to add unit tests or examples, just add a source file in `test/` 127or `example/` and then re-run the CMake generation step so the new source 128file is known to the build system. Let's suppose the relative path from the 129root of the project to the new source file is `path/to/file.cpp`. When you 130re-run the CMake generation step, a new target named `path.to.file` will be 131created, and a test of the same name will also be created. Hence, 132```shell 133cd build # Go back to the build directory 134cmake --build . --target path.to.file # Builds the program associated to path/to/file.cpp 135ctest -R path.to.file # Runs the program as a test 136``` 137 138> #### Tip for Sublime Text users 139> If you use the provided [hana.sublime-project](hana.sublime-project) file, 140> you can select the "[Hana] Build current file" build system. When viewing a 141> file to which a target is associated (like a test or an example), you can 142> then compile it by pressing ⌘B, or compile and then run it using ⇧⌘B. 143 144 145## Project organization 146The project is organized in a couple of subdirectories. 147- The [benchmark](benchmark) directory contains compile-time and runtime 148 benchmarks to make sure the library is as fast as advertised. The benchmark 149 code is written mostly in the form of [eRuby][] templates. The templates 150 are used to generate C++ files which are then compiled while gathering 151 compilation and execution statistics. 152- The [cmake](cmake) directory contains various CMake modules and other 153 scripts needed by the build system. 154- The [doc](doc) directory contains configuration files needed to generate 155 the documentation. The `doc/html` subdirectory is automatically ignored 156 by Git; you can conveniently store a local copy of the documentation by 157 cloning the `gh-pages` branch into that directory, as explained above. 158- The [example](example) directory contains the source code for all the 159 examples of both the tutorial and the reference documentation. 160- The [include](include) directory contains the library itself, which is 161 header only. 162- The [test](test) directory contains the source code for all the unit tests. 163 164 165## Contributing 166Please see [CONTRIBUTING.md](CONTRIBUTING.md). 167 168 169## License 170Please see [LICENSE.md](LICENSE.md). 171 172 173## Releasing 174To release a new version of Hana, use the `util/release.sh` script. The script 175will merge `develop` to `master`, create a tag on `master` and then bump the 176version on `develop`. The tag on `master` will be annotated with the contents 177of the `RELEASE_NOTES.md` file. Once the `release.sh` script has been run, the 178`master` and `develop` branches should be pushed manually, as well as the tag 179that was created on `master`. Finally, create a GitHub release pointing to the 180new tag on `master`. 181 182 183<!-- Links --> 184[badge.Appveyor]: https://ci.appveyor.com/api/projects/status/github/boostorg/hana?svg=true&branch=master 185[badge.Gitter]: https://img.shields.io/badge/gitter-join%20chat-blue.svg 186[badge.Travis]: https://travis-ci.org/boostorg/hana.svg?branch=master 187[badge.version]: https://badge.fury.io/gh/boostorg%2Fhana.svg 188[badge.Wandbox]: https://img.shields.io/badge/try%20it-online-blue.svg 189[CMake]: http://www.cmake.org 190[Doxygen]: http://www.doxygen.org 191[eRuby]: http://en.wikipedia.org/wiki/ERuby 192[Hana.docs]: http://boostorg.github.io/hana 193[Hana.wiki]: https://github.com/boostorg/hana/wiki 194
