hana

Impulso.Hana

Su biblioteca estándar para metaprogramación

Descripción general

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

Documentación

Puede explorar la documentación en línea en http://boostorg.github.io/hana. La documentación cubre todo lo que necesita, incluida la instalación de la biblioteca, un tutorial que explica qué es Hana y cómo usarlo y una extensa sección de referencia con ejemplos. El resto de este README es principalmente para personas que desean trabajar en la biblioteca misma, no para sus usuarios.

Se puede obtener una copia sin conexión de la documentación consultando la sucursal gh-pages . Para evitar sobrescribir el directorio actual, puedes clonar la rama gh-pages en un subdirectorio como doc/html :

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

Después de emitir esto, doc/html contendrá exactamente el mismo sitio web estático que está disponible en línea. Tenga en cuenta que Git ignora automáticamente doc/html , por lo que actualizar la documentación no contaminará su índice.

Hackear a Hana

Prepararse para trabajar en Hana es fácil. Primero, necesitará una instalación de CMake. Una vez hecho esto, puede cd a la raíz del proyecto y configurar el directorio de compilación:

mkdir build
cmake -S . -B build

A veces querrás especificar un compilador personalizado porque el compilador del sistema es demasiado antiguo:

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

Por lo general, esto funcionará bien. Sin embargo, en algunos sistemas más antiguos, la biblioteca estándar y/o el compilador proporcionado de forma predeterminada no son compatibles con C++14. Si este es tu caso, la wiki tiene más información sobre cómo configurarlo en diferentes sistemas.

Normalmente, Hana intenta encontrar encabezados de Boost si los tiene en su sistema. También está bien si no los tienes; En ese caso, algunas pruebas que requieren los encabezados Boost se desactivarán. Sin embargo, si desea que Hana utilice una instalación personalizada de Boost, puede especificar la ruta a esta instalación personalizada:

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

Ahora puede compilar y ejecutar las pruebas unitarias y los ejemplos:

cmake --build build --target check

Debe tener en cuenta que compilar las pruebas unitarias consume bastante tiempo y RAM, especialmente las pruebas para adaptadores externos. Esto se debe al hecho de que las pruebas unitarias de Hana son muy exhaustivas y también a que las secuencias heterogéneas en otras bibliotecas tienden a tener un rendimiento horrible en tiempo de compilación.

También hay objetivos opcionales que se habilitan sólo cuando el software requerido está disponible en su computadora. Por ejemplo, generar la documentación requiere que Doxygen esté instalado. Se imprimirá un mensaje informativo durante el paso de generación de CMake cada vez que se deshabilite un objetivo opcional. Puede instalar cualquier software que falte y luego volver a ejecutar la generación de CMake para actualizar la lista de objetivos disponibles.

Consejo

Puede utilizar el objetivo help para obtener una lista de todos los objetivos disponibles.

Si desea agregar pruebas unitarias o ejemplos, simplemente agregue un archivo fuente en test/ o example/ y luego vuelva a ejecutar el paso de generación de CMake para que el sistema de compilación conozca el nuevo archivo fuente. Supongamos que la ruta relativa desde la raíz del proyecto hasta el nuevo archivo fuente es path/to/file.cpp . Cuando vuelva a ejecutar el paso de generación de CMake, se creará un nuevo destino denominado path.to.file y también se creará una prueba con el mismo nombre. Por eso,

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 

Consejo para usuarios de Sublime Text

Si utiliza el archivo hana.sublime-project proporcionado, puede seleccionar el sistema de compilación "[Hana] Crear archivo actual". Al visualizar un archivo al que está asociado un objetivo (como una prueba o un ejemplo), puede compilarlo presionando ⌘B, o compilarlo y luego ejecutarlo usando ⇧⌘B.

organización del proyecto

El proyecto está organizado en un par de subdirectorios.

• El directorio de pruebas contiene pruebas comparativas en tiempo de compilación y ejecución para garantizar que la biblioteca sea tan rápida como se anuncia. El código de referencia está escrito principalmente en forma de plantillas de eRuby. Las plantillas se utilizan para generar archivos C++ que luego se compilan mientras se recopilan estadísticas de compilación y ejecución.
• El directorio cmake contiene varios módulos CMake y otros scripts necesarios para el sistema de compilación.
• El directorio doc contiene los archivos de configuración necesarios para generar la documentación. Git ignora automáticamente el subdirectorio doc/html ; Puede almacenar cómodamente una copia local de la documentación clonando la rama gh-pages en ese directorio, como se explicó anteriormente.
• El directorio de ejemplo contiene el código fuente de todos los ejemplos tanto del tutorial como de la documentación de referencia.
• El directorio de inclusión contiene la biblioteca en sí, que es solo el encabezado.
• El directorio de prueba contiene el código fuente de todas las pruebas unitarias.

Contribuyendo

Consulte CONTRIBUTING.md.

Licencia

Consulte LICENCIA.md.

Liberando

El lanzamiento ahora se realiza exclusivamente a través del proceso de lanzamiento de Boost. No hay versiones separadas de Hana ya que la biblioteca ahora es bastante estable.