toml++ في C++: دليل شامل مع أمثلة عملية

1. ما هي toml++ ولماذا تحتاجها؟

TOML (Tom's Obvious Minimal Language) هو تنسيق لملفات الإعدادات، صُمم ليكون بديلاً عن INI و YAML و JSON. يتميز بكونه قابلاً للقراءة بشكل كبير من قبل البشر، ويمكن تحويله بسهولة إلى جداول تجزئة (hash tables)، وبساطة تحليله (parsing). على عكس YAML، لا يسمح TOML بالغموض (مثل المسافات البادئة أو أنواع البيانات)، وعلى عكس JSON، لا يتطلب علامات اقتباس للمفاتيح ويدعم التعليقات.

toml++ (المعروفة أيضًا باسم tomlplusplus) هي مكتبة حديثة من نوع header-only لتحليل (parsing) وإنشاء ملفات TOML بلغة C++17 وما فوق. لا تحتاج إلى بناء (build) منفصل؛只需 قم بتضمين ملف الرأس (header file) لتحصل على الوظائف الكاملة. هذا يجعلها الخيار الأمثل للمشاريع التي تهمها سهولة التكامل والأداء العالي والكتابة الصارمة للأنواع (strict typing).

لماذا تستخدم toml++؟ أولاً، توفر دعمًا كاملاً لمواصفات TOML v1.0، بما في ذلك الجداول المضمنة (inline tables)، ومصفوفات الجداول (arrays of tables)، والتواريخ، والأوقات، والتواريخ المحلية. ثانيًا، تمت كتابتها مع التركيز على أمان الأنواع: ستحصل على قيم ذات أنواع محددة بدقة (std::string, int64_t, double, bool, toml::date، إلخ) بدلاً من كائن خام يشبه JSON. ثالثًا، إنها سريعة بشكل لا يصدق ولديها حد أدنى من التبعيات (فقط مكتبة C++17 القياسية).

2. طريقة التثبيت

toml++ هي مكتبة من نوع header-only. هذا يعني أنك لست بحاجة إلى ترجمتها بشكل منفصل. يكفي نسخ ملفات الرأس إلى مشروعك وتضمينها.

الطريقة الأولى: Vcpkg (موصى به لنظامي Windows و Linux)

# التثبيت عبر vcpkg
vcpkg install tomlplusplus

# التضمين في ملف CMakeLists.txt
find_package(tomlplusplus CONFIG REQUIRED)
target_link_libraries(my_project PRIVATE tomlplusplus::tomlplusplus)

الطريقة الثانية: Conan

# التثبيت عبر Conan
conan install tomlplusplus/3.4.0@

# في ملف conanfile.txt
[requires]
tomlplusplus/3.4.0

[generators]
CMakeDeps

الطريقة الثالثة: التثبيت اليدوي (الأسهل)

# قم بتنزيل أحدث إصدار من GitHub
wget https://github.com/marzer/tomlplusplus/archive/refs/tags/v3.4.0.tar.gz
tar -xzf v3.4.0.tar.gz

# انسخ مجلد include/toml++ إلى مشروعك
cp -r tomlplusplus-3.4.0/include/toml++ /path/to/your/project/include/

# في الكود الخاص بك، قم بالتضمين ببساطة:
#include <toml++/toml.h>

الطريقة الرابعة: CMake FetchContent (لمشاريع CMake)

include(FetchContent)
FetchContent_Declare(
    tomlplusplus
    GIT_REPOSITORY https://github.com/marzer/tomlplusplus.git
    GIT_TAG v3.4.0
)
FetchContent_MakeAvailable(tomlplusplus)

target_link_libraries(my_project PRIVATE tomlplusplus::tomlplusplus)

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

لنقم بإنشاء ملف config.toml:

# config.toml
title = "مثال على الإعدادات"

[server]
host = "localhost"
port = 8080
debug = true

[database]
name = "mydb"
user = "admin"
password = "secret123"

الآن لنكتب كود C++ لقراءته:

#include <toml++/toml.h>
#include <iostream>
#include <filesystem>

int main() {
    // 1. تحليل الملف
    auto config = toml::parse_file("config.toml");

    // 2. قراءة القيم البسيطة
    std::string title = config["title"].value_or("default");
    std::cout << "العنوان: " << title << std::endl;

    // 3. قراءة الجداول المتداخلة
    auto server = config["server"];
    std::string host = server["host"].value_or("localhost");
    int port = server["port"].value_or(3000);
    bool debug = server["debug"].value_or(false);

    std::cout << "الخادم: " << host << ":" << port << std::endl;
    std::cout << "وضع التصحيح: " << (debug ? "مفعل" : "معطل") << std::endl;

    return 0;
}