hana

Impulso.Hana

Sua biblioteca padrão para metaprogramação

Visão geral

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

Documentação

Você pode navegar pela documentação online em http://boostorg.github.io/hana. A documentação cobre tudo que você precisa, incluindo a instalação da biblioteca, um tutorial explicando o que é Hana e como usá-lo, e uma extensa seção de referência com exemplos. O restante deste README é principalmente para pessoas que desejam trabalhar na biblioteca em si, e não para seus usuários.

Uma cópia offline da documentação pode ser obtida verificando o branch gh-pages . Para evitar a substituição do diretório atual, você pode clonar a ramificação gh-pages em um subdiretório como doc/html :

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

Depois de emitir isso, doc/html conterá exatamente o mesmo site estático que está disponível online. Observe que doc/html é automaticamente ignorado pelo Git, portanto, atualizar a documentação não poluirá seu índice.

Hackeando Hana

Preparar-se para trabalhar em Hana é fácil. Primeiro, você precisará de uma instalação do CMake. Feito isso, você pode cd para a raiz do projeto e configurar o diretório de construção:

mkdir build
cmake -S . -B build

Às vezes, você desejará especificar um compilador personalizado porque o compilador do sistema é muito antigo:

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

Normalmente, isso funcionará perfeitamente. No entanto, em alguns sistemas mais antigos, a biblioteca e/ou compilador padrão fornecido por padrão não oferece suporte a C++14. Se este for o seu caso, o wiki traz mais informações sobre como configurá-lo em diferentes sistemas.

Normalmente, Hana tenta encontrar cabeçalhos Boost se você os tiver em seu sistema. Também não há problema se você não os tiver; alguns testes que exigem os cabeçalhos Boost serão desativados nesse caso. No entanto, se quiser que Hana use uma instalação personalizada do Boost, você pode especificar o caminho para esta instalação personalizada:

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

Agora você pode criar e executar os testes de unidade e os exemplos:

cmake --build build --target check

Você deve estar ciente de que compilar os testes de unidade consome muito tempo e consome RAM, especialmente os testes para adaptadores externos. Isso se deve ao fato de que os testes unitários de Hana são muito completos e também porque sequências heterogêneas em outras bibliotecas tendem a ter um desempenho horrível em tempo de compilação.

Existem também destinos opcionais que são ativados somente quando o software necessário está disponível no seu computador. Por exemplo, a geração da documentação requer a instalação do Doxygen. Uma mensagem informativa será impressa durante a etapa de geração do CMake sempre que um alvo opcional for desabilitado. Você pode instalar qualquer software ausente e executar novamente a geração do CMake para atualizar a lista de destinos disponíveis.

Dica

Você pode usar o alvo help para obter uma lista de todos os alvos disponíveis.

Se você quiser adicionar testes de unidade ou exemplos, basta adicionar um arquivo de origem em test/ ou example/ e, em seguida, executar novamente a etapa de geração do CMake para que o novo arquivo de origem seja conhecido pelo sistema de compilação. Vamos supor que o caminho relativo da raiz do projeto até o novo arquivo de origem seja path/to/file.cpp . Ao executar novamente a etapa de geração do CMake, um novo destino chamado path.to.file será criado e um teste com o mesmo nome também será criado. Por isso,

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 

Dica para usuários de Sublime Text

Se você usar o arquivo hana.sublime-project fornecido, poderá selecionar o sistema de compilação "[Hana] Construir arquivo atual". Ao visualizar um arquivo ao qual um destino está associado (como um teste ou exemplo), você pode compilá-lo pressionando ⌘B ou compilar e executá-lo usando ⇧⌘B.

Organização do projeto

O projeto está organizado em alguns subdiretórios.

• O diretório benchmark contém benchmarks de tempo de compilação e tempo de execução para garantir que a biblioteca seja tão rápida quanto anunciada. O código de benchmark é escrito principalmente na forma de modelos eRuby. Os modelos são usados ​​para gerar arquivos C++ que são então compilados enquanto coletam estatísticas de compilação e execução.
• O diretório cmake contém vários módulos CMake e outros scripts necessários ao sistema de compilação.
• O diretório doc contém arquivos de configuração necessários para gerar a documentação. O subdiretório doc/html é automaticamente ignorado pelo Git; você pode armazenar convenientemente uma cópia local da documentação clonando a ramificação gh-pages nesse diretório, conforme explicado acima.
• O diretório de exemplo contém o código-fonte de todos os exemplos do tutorial e da documentação de referência.
• O diretório include contém a própria biblioteca, que é apenas cabeçalho.
• O diretório test contém o código-fonte de todos os testes unitários.

Contribuindo

Consulte CONTRIBUTING.md.

Licença

Consulte LICENSE.md.

Liberando

A liberação agora é feita exclusivamente por meio do processo de liberação do Boost. Não há versões separadas do Hana, pois a biblioteca agora está bastante estável.