hana

دفعة.هانا

مكتبتك القياسية للبرمجة الوصفية

ملخص

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

التوثيق

يمكنك تصفح الوثائق عبر الإنترنت على http://boostorg.github.io/hana. تغطي الوثائق كل ما تحتاج إليه بما في ذلك تثبيت المكتبة، وبرنامج تعليمي يشرح ماهية Hana وكيفية استخدامها، وقسم مرجعي شامل يحتوي على أمثلة. ما تبقى من ملف README هذا مخصص في الغالب للأشخاص الذين يرغبون في العمل على المكتبة نفسها، وليس لمستخدميها.

يمكن الحصول على نسخة من الوثائق دون الاتصال بالإنترنت عن طريق مراجعة فرع gh-pages . لتجنب الكتابة فوق الدليل الحالي، يمكنك استنساخ فرع gh-pages في دليل فرعي مثل doc/html :

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

بعد إصدار هذا، سيحتوي doc/html على نفس موقع الويب الثابت المتوفر عبر الإنترنت. لاحظ أن Git يتجاهل doc/html تلقائيًا، لذا فإن تحديث الوثائق لن يؤدي إلى تلويث الفهرس الخاص بك.

القرصنة على هناء

يعد إعداد نفسك للعمل على Hana أمرًا سهلاً. أولا، سوف تحتاج إلى تثبيت CMake. بمجرد الانتهاء من ذلك، يمكنك cd إلى جذر المشروع وإعداد دليل البناء:

mkdir build
cmake -S . -B build

في بعض الأحيان، قد ترغب في تحديد مترجم مخصص لأن مترجم النظام قديم جدًا:

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

عادة، هذا سوف يعمل بشكل جيد. ومع ذلك، في بعض الأنظمة القديمة، لا تدعم المكتبة القياسية و/أو المترجم المقدم افتراضيًا C++ 14. إذا كانت هذه هي حالتك، فإن موقع wiki يحتوي على مزيد من المعلومات حول إعدادك على أنظمة مختلفة.

عادةً، تحاول Hana العثور على رؤوس Boost إذا كانت لديك على نظامك. لا بأس أيضًا إذا لم يكن لديك؛ سيتم تعطيل بعض الاختبارات التي تتطلب رؤوس Boost في هذه الحالة. ومع ذلك، إذا كنت تريد أن تستخدم Hana تثبيتًا مخصصًا لـ Boost، فيمكنك تحديد المسار إلى هذا التثبيت المخصص:

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

يمكنك الآن إنشاء وتشغيل اختبارات الوحدة والأمثلة:

cmake --build build --target check

يجب أن تدرك أن تجميع اختبارات الوحدة يستغرق وقتًا طويلاً ويستهلك ذاكرة الوصول العشوائي (RAM)، خاصة اختبارات المحولات الخارجية. ويرجع ذلك إلى حقيقة أن اختبارات وحدة Hana شاملة للغاية، كما أن التسلسلات غير المتجانسة في المكتبات الأخرى تميل إلى الحصول على أداء سيئ في وقت الترجمة.

هناك أيضًا أهداف اختيارية يتم تمكينها فقط عندما يتوفر البرنامج المطلوب على جهاز الكمبيوتر الخاص بك. على سبيل المثال، يتطلب إنشاء الوثائق تثبيت Doxygen. ستتم طباعة رسالة إعلامية أثناء خطوة إنشاء CMake عندما يتم تعطيل هدف اختياري. يمكنك تثبيت أي برنامج مفقود ثم إعادة تشغيل جيل CMake لتحديث قائمة الأهداف المتاحة.

نصيحة

يمكنك استخدام هدف help للحصول على قائمة بجميع الأهداف المتاحة.

إذا كنت ترغب في إضافة اختبارات وحدة أو أمثلة، فما عليك سوى إضافة ملف مصدر في test/ أو example/ ثم إعادة تشغيل خطوة إنشاء CMake حتى يصبح الملف المصدر الجديد معروفًا لنظام الإنشاء. لنفترض أن المسار النسبي من جذر المشروع إلى الملف المصدر الجديد هو path/to/file.cpp . عند إعادة تشغيل خطوة إنشاء CMake، سيتم إنشاء هدف جديد يسمى path.to.file ، كما سيتم إنشاء اختبار بنفس الاسم. لذلك،

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 

نصيحة لمستخدمي Sublime Text

إذا كنت تستخدم ملف hana.sublime-project المقدم، فيمكنك تحديد نظام البناء "[Hana] Build current file". عند عرض ملف يرتبط به هدف (مثل اختبار أو مثال)، يمكنك بعد ذلك تجميعه بالضغط على ⌘B، أو تجميعه ثم تشغيله باستخدام ⇧⌘B.

تنظيم المشروع

يتم تنظيم المشروع في اثنين من الدلائل الفرعية.

• يحتوي الدليل المعياري على معايير وقت الترجمة ووقت التشغيل للتأكد من أن المكتبة سريعة كما تم الإعلان عنها. تتم كتابة الكود المعياري في الغالب في شكل قوالب eRuby. يتم استخدام القوالب لإنشاء ملفات C++ والتي يتم تجميعها بعد ذلك أثناء جمع إحصائيات التجميع والتنفيذ.
• يحتوي دليل cmake على وحدات CMake المختلفة والبرامج النصية الأخرى التي يحتاجها نظام الإنشاء.
• يحتوي دليل المستند على ملفات التكوين اللازمة لإنشاء الوثائق. يتم تجاهل الدليل الفرعي doc/html تلقائيًا بواسطة Git؛ يمكنك بسهولة تخزين نسخة محلية من الوثائق عن طريق استنساخ فرع gh-pages في هذا الدليل، كما هو موضح أعلاه.
• يحتوي دليل المثال على الكود المصدري لجميع أمثلة كل من البرنامج التعليمي والوثائق المرجعية.
• يحتوي دليل التضمين على المكتبة نفسها، وهي رأسية فقط.
• يحتوي دليل الاختبار على الكود المصدري لجميع اختبارات الوحدة.

المساهمة

يرجى الاطلاع على CONTRIBUTING.md.

رخصة

يرجى الاطلاع على LICENSE.md.

الافراج

يتم الإصدار الآن حصريًا عبر عملية إصدار Boost. لا توجد إصدارات منفصلة لـ Hana نظرًا لأن المكتبة الآن مستقرة جدًا.