عن المشروع

dotcfg هي حزمة Rust لإدارة إعدادات التطبيقات بمرونة وتحكّم من المطوّر. وخلافًا للحزم التي تفرض استراتيجية مجلدات ثابتة أو تدعم القراءة فقط، تتيح لك dotcfg اختيار مكان تخزين الإعدادات والصيغ التي تريد تضمينها، مع إبقاء الملف التنفيذي صغيرًا عبر دعم الصيغ المُبوَّب بالميزات. ### مواقع التخزين افتراضيًا تُخزَّن الإعدادات في `~/.toolname/config.toml`، على غرار `.cargo` أو `.ssh`. ويمكن للمستخدمين اختيار مسارات XDG القياسية عبر `.xdg()`، أو التخزين في مسار مطلق عشوائي عبر `.at_dir()`، أو ترك dotcfg يصعد من دليل العمل الحالي لتحديد إعداد محلي بالمشروع (على غرار طريقة بحث Git عن `.git`). ### دعم الصيغ TOML مُفعَّل افتراضيًا. أما JSON وYAML فهما متاحان كميزتين اختياريتين (`json` و`yaml`)، ويمكن الجمع بينهما ليقرأ ملف تنفيذي واحد صيغًا متعددة. كما يمكن تعيين اسم ملف مخصص (مثل `settings.json`). ### استراتيجيات التحميل - `load()` — يُرجع `None` عندما لا يكون الملف موجودًا، تاركًا للتطبيق قرار كيفية المتابعة. - `load_or_error()` — يُرجع خطأً إذا كان الملف مفقودًا، وهو مناسب لواجهات CLI التي تتطلب إعدادًا مسبقًا. - `load_or_default()` — يُنشئ الملف معبّأ بقيم `Default` عند أول استخدام. ### الوصول لكل مفتاح اقرأ واكتب مفاتيح فردية دون تحميل الإعداد الكامل أو الكتابة فوقه: - `cfg.get("user.name")` / `cfg.set("user.name", "jane")` - `cfg.get_as::<u16>("port")` / `cfg.set_val("port", 8080u16)` المفاتيح المتداخلة باستخدام الترميز النقطي (مثل `section.field`) مدعومة وتُقابل بشكل طبيعي جداول TOML وكائنات JSON وخرائط YAML. وتُنشأ الملفات أو المجلدات المفقودة عند الكتابة. ### تجاوزات متغيرات البيئة تتيح تجاوزات متغيرات البيئة المعتمدة على بادئة أن يأخذ `MYAPP_PORT=9000` الأولوية على قيمة الملف دون تعديل حالة القرص. ويُرجع `get` السلسلة الخام، بينما يحلّل `get_as` القيم المنطقية والأرقام وقيم `Vec` المفصولة بفواصل. وتبقى عمليات الكتابة موجّهة إلى ملف الإعدادات فقط. ### التكامل مع CLI تعمل المكتبة جنبًا إلى جنب مع `clap` لتطبيق سلسلة الأولوية القياسية: علامة CLI > ملف الإعدادات > القيمة الافتراضية الاحتياطية. ### أدوات أخرى تتوفر `exists()` و`dir()` و`file_path()` و`delete_file()` و`delete_dir()` للفحص والتنظيف البرمجي. ### الترخيص مرخّصة بشكل مزدوج تحت MIT OR Apache-2.0.