1. ما هي مكتبة magic_enum ولماذا تحتاجها؟

في لغة C++، تُعد التعدادات (enum و enum class) أداة قوية لإنشاء ثوابت مسماة، لكنها تعاني من عيب جوهري — وهو غياب الانعكاس (Reflection) المدمج. لا توفر لغة C++ القياسية طريقة بسيطة للحصول على التمثيل النصي لقيمة تعداد، أو المرور على جميع عناصره، أو معرفة عدد الخيارات المتاحة. يضطر المطورون إلى كتابة دوال مساعدة يدويًا، أو استخدام وحدات ماكرو، أو اللجوء إلى مولدات أكواد خارجية، مما يؤدي إلى تكرار الكود وزيادة احتمالية الأخطاء.

تأتي مكتبة magic_enum لحل هذه المشكلة، حيث توفر مجموعة أدوات قوية وسهلة الاستخدام للتعامل مع التعدادات في وقت الترجمة ووقت التنفيذ. تستخدم المكتبة قوالب C++17 المتقدمة وآليات المترجم الداخلية (مثل __PRETTY_FUNCTION__) لاستخراج معلومات التعدادات تلقائيًا. باستخدام magic_enum، يمكنك الحصول على الاسم النصي لأي قيمة، وتحويل نص إلى قيمة تعداد، والمرور على جميع عناصر التعداد، ومعرفة عددها، وغير ذلك الكثير — دون الحاجة إلى كتابة أي كود مساعد.

هذه المكتبة لا غنى عنها في مهام تسجيل الأحداث (Logging)، والتسلسل وإلغاء التسلسل (Serialization/Deserialization)، وإنشاء ملفات التكوين، وتحليل إدخال المستخدم، والاختبارات، وأي مهام أخرى تتطلب عملاً ديناميكيًا مع التعدادات. تجعل المكتبة الكود أنظف وأكثر أمانًا وتقلل بشكل كبير من حجم الكود النمطي. تُعد magic_enum المكتبة الأكثر شيوعًا ونضجًا لانعكاس التعدادات في C++، وهي مدعومة على جميع المترجمات الرئيسية (GCC, Clang, MSVC).

2. طريقة التركيب (Installation)

مكتبة magic_enum هي مكتبة من نوع "header-only"، أي أنها تتكون من ملف رأس واحد فقط. وهذا يجعل عملية تركيبها بسيطة للغاية. لا تحتاج إلى بنائها كمكتبة منفصلة، فقط قم بنسخ الملف magic_enum.hpp إلى مشروعك وقم بتضمينه.

ومع ذلك، لتسهيل إدارة التبعيات، يُنصح باستخدام أنظمة بناء مثل CMake (عبر FetchContent أو find_package) أو مديري الحزم مثل vcpkg أو Conan.

الطريقة الأولى: تنزيل الملف يدويًا (الأسهل)

1. انتقل إلى صفحة الإصدارات على GitHub: https://github.com/Neargye/magic_enum/releases
2. قم بتنزيل أحدث إصدار من الملف magic_enum.hpp.
3. ضعه في مجلد مشروعك (مثلاً في include/).
4. قم بتضمينه في الكود: #include "magic_enum.hpp"

الطريقة الثانية: عبر vcpkg (موصى به لنظام Windows)

vcpkg install magic-enum

الطريقة الثالثة: عبر Conan

conan install magic_enum/0.9.5@

الطريقة الرابعة: عبر CMake FetchContent (موصى به للمشاريع الجديدة)

أضف الكود التالي إلى ملف CMakeLists.txt الخاص بك:

include(FetchContent)
FetchContent_Declare(
  magic_enum
  GIT_REPOSITORY https://github.com/Neargye/magic_enum.git
  GIT_TAG v0.9.5 # أو أحدث علامة مستقرة
)
FetchContent_MakeAvailable(magic_enum)

target_link_libraries(your_target PRIVATE magic_enum::magic_enum)

ملاحظة هامة: لكي تعمل مكتبة magic_enum، تحتاج إلى مترجم يدعم معيار C++17. تأكد من تفعيل المعيار المناسب في مشروعك (مثلاً: set(CMAKE_CXX_STANDARD 17) أو العلم -std=c++17).

3. البداية السريعة — مثال عملي بسيط

لنبدأ بأبسط مثال