hana

Tingkatkan.Hana

Perpustakaan standar Anda untuk metaprogramming

Ringkasan

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

Dokumentasi

Anda dapat menelusuri dokumentasi online di http://boostorg.github.io/hana. Dokumentasinya mencakup semua yang Anda perlukan termasuk menginstal perpustakaan, tutorial yang menjelaskan apa itu Hana dan cara menggunakannya, dan bagian referensi ekstensif dengan contoh. Sisa dari README ini sebagian besar diperuntukkan bagi orang-orang yang ingin mengerjakan perpustakaan itu sendiri, bukan untuk penggunanya.

Salinan dokumentasi offline dapat diperoleh dengan memeriksa cabang gh-pages . Untuk menghindari penimpaan direktori saat ini, Anda dapat mengkloning cabang gh-pages ke dalam subdirektori seperti doc/html :

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

Setelah mengeluarkan ini, doc/html akan berisi situs web statis yang sama persis dengan yang tersedia online. Perhatikan bahwa doc/html secara otomatis diabaikan oleh Git sehingga memperbarui dokumentasi tidak akan mencemari indeks Anda.

Meretas Hana

Menyiapkan diri Anda untuk bekerja pada Hana itu mudah. Pertama, Anda memerlukan instalasi CMake. Setelah ini selesai, Anda dapat melakukan cd ke root proyek dan mengatur direktori build:

mkdir build
cmake -S . -B build

Terkadang, Anda ingin menentukan kompiler khusus karena kompiler sistem terlalu tua:

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

Biasanya, ini akan berfungsi dengan baik. Namun, pada beberapa sistem lama, pustaka standar dan/atau kompiler yang disediakan secara default tidak mendukung C++14. Jika ini kasus Anda, wiki memiliki informasi lebih lanjut tentang menyiapkan Anda pada sistem yang berbeda.

Biasanya, Hana mencoba menemukan header Boost jika Anda memilikinya di sistem Anda. Tidak masalah juga jika Anda tidak memilikinya; beberapa tes yang memerlukan header Boost akan dinonaktifkan dalam kasus tersebut. Namun, jika Anda ingin Hana menggunakan instalasi khusus Boost, Anda dapat menentukan jalur ke instalasi khusus ini:

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

Anda sekarang dapat membuat dan menjalankan pengujian unit dan contohnya:

cmake --build build --target check

Anda harus menyadari bahwa mengkompilasi pengujian unit cukup memakan waktu dan RAM, terutama pengujian untuk adaptor eksternal. Hal ini disebabkan oleh fakta bahwa pengujian unit Hana sangat teliti, dan juga urutan heterogen di perpustakaan lain cenderung memiliki kinerja waktu kompilasi yang buruk.

Ada juga target opsional yang diaktifkan hanya bila perangkat lunak yang diperlukan tersedia di komputer Anda. Misalnya, membuat dokumentasi memerlukan instalasi Doxygen. Pesan informatif akan dicetak selama langkah pembuatan CMake setiap kali target opsional dinonaktifkan. Anda dapat menginstal perangkat lunak apa pun yang hilang lalu menjalankan kembali pembuatan CMake untuk memperbarui daftar target yang tersedia.

Tip

Anda dapat menggunakan target help untuk mendapatkan daftar semua target yang tersedia.

Jika Anda ingin menambahkan pengujian unit atau contoh, cukup tambahkan file sumber di test/ atau example/ lalu jalankan kembali langkah pembuatan CMake sehingga file sumber baru diketahui oleh sistem build. Misalkan jalur relatif dari akar proyek ke file sumber baru adalah path/to/file.cpp . Saat Anda menjalankan kembali langkah pembuatan CMake, target baru bernama path.to.file akan dibuat, dan pengujian dengan nama yang sama juga akan dibuat. Karena itu,

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 

Tip untuk pengguna Sublime Text

Jika Anda menggunakan file proyek hana.sublime yang disediakan, Anda dapat memilih sistem build "[Hana] Build current file". Saat melihat file yang dikaitkan dengan target (seperti pengujian atau contoh), Anda dapat mengompilasinya dengan menekan ⌘B, atau mengkompilasi lalu menjalankannya menggunakan ⇧⌘B.

Organisasi proyek

Proyek ini diatur dalam beberapa subdirektori.

• Direktori benchmark berisi benchmark waktu kompilasi dan runtime untuk memastikan perpustakaan bekerja secepat yang diiklankan. Kode benchmark sebagian besar ditulis dalam bentuk template eRuby. Templat digunakan untuk menghasilkan file C++ yang kemudian dikompilasi sambil mengumpulkan statistik kompilasi dan eksekusi.
• Direktori cmake berisi berbagai modul CMake dan skrip lain yang diperlukan oleh sistem build.
• Direktori doc berisi file konfigurasi yang diperlukan untuk menghasilkan dokumentasi. Subdirektori doc/html secara otomatis diabaikan oleh Git; Anda dapat dengan mudah menyimpan salinan dokumentasi lokal dengan mengkloning cabang gh-pages ke dalam direktori tersebut, seperti dijelaskan di atas.
• Direktori contoh berisi kode sumber untuk semua contoh tutorial dan dokumentasi referensi.
• Direktori include berisi perpustakaan itu sendiri, yang hanya berupa header.
• Direktori pengujian berisi kode sumber untuk semua pengujian unit.

Berkontribusi

Silakan lihat KONTRIBUSI.md.

Lisensi

Silakan lihat LISENSI.md.

Melepaskan

Pelepasan kini dilakukan secara eksklusif melalui proses rilis Boost. Tidak ada rilis terpisah dari Hana karena perpustakaannya sekarang cukup stabil.