ابدأ مع كنوز

مرحباً بك في لغة كنوز البرمجية! كنوز هي لغة برمجة عربية حديثة مصممة لجعل البرمجة أكثر وضوحاً وسهولة للمتحدثين بالعربية. تتميز كنوز بنظام أنواع قوي، معالجة أخطاء متقدمة، ودعم كامل للبرمجة المتزامنة بما في ذلك الخيوط الخضراء (M:N scheduler) والأنواع المرتبطة المعممة (GATs).

هذا الدليل سيأخذك خطوة بخطوة من التثبيت إلى كتابة أول برنامج لك. في نهاية هذا الدليل، ستكون قادراً على:

• تثبيت كنوز على جهازك
• إنشاء وتشغيل برامج كنوز
• فهم البنية الأساسية للمشاريع
• البدء في تعلم ميزات اللغة

تثبيت كنوز

التثبيت السريع (موصى به)

أسرع وأسهل طريقة لتثبيت كنوز على Linux أو macOS:

curl -fsSL https://sh.knoz.dev | sh

هذا الأمر سيقوم تلقائياً بـ:

• تحديد نظام التشغيل والمعمارية
• تحميل النسخة المناسبة
• تثبيت كنوز في المسار الصحيح
• إضافة كنوز إلى PATH

Windows

لمستخدمي Windows، حمّل المثبت من صفحة التحميل:

تحميل كنوز لـ Windows ←

التحقق من التثبيت

# عرض النسخة
knoz --نسخة

# عرض المساعدة
knoz --مساعدة

يجب أن ترى:

كنوز - لغة البرمجة العربية
الإصدار: 1.0.0

للمزيد من خيارات التثبيت: صفحة التحميل ←

---

أول برنامج لك

1. إنشاء مشروع جديد

# إنشاء مشروع جديد
knoz جديد مرحبا
cd مرحبا

هذا ينشئ الهيكل التالي:

مرحبا/
├── كنوز.toml
└── مصدر/
    └── رئيسي.كنز

2. محتوى الملف

افتح مصدر/رئيسي.كنز وستجد:

دالة رئيسية() {
    طباعة("مرحباً بالعالم!")؛
}

3. تشغيل البرنامج

# طريقة 1: تشغيل مباشر
knoz شغّل

# طريقة 2: بناء ثم تشغيل
knoz ابنِ
./مرحبا  # Linux/macOS
مرحبا.exe  # Windows

النتيجة:

مرحباً بالعالم!

---

مثال: حاسبة بسيطة

لنكتب برنامجاً أكثر تفاعلية!

1. إنشاء المشروع

knoz جديد حاسبة
cd حاسبة

2. كتابة الكود

عدّل مصدر/رئيسي.كنز:

دالة رئيسية() {
    طباعة("=== حاسبة بسيطة ===")؛
    طباعة()؛

    // إدخال الأرقام
    دع أ = 10؛
    دع ب = 5؛

    // العمليات الحسابية
    دع جمع = أ + ب؛
    دع طرح = أ - ب؛
    دع ضرب = أ * ب؛
    دع قسمة = أ / ب؛

    // عرض النتائج
    طباعة("{} + {} = {}"، أ، ب، جمع)؛
    طباعة("{} - {} = {}"، أ، ب، طرح)؛
    طباعة("{} × {} = {}"، أ، ب، ضرب)؛
    طباعة("{} ÷ {} = {}"، أ، ب، قسمة)؛
}

3. التشغيل

knoz شغّل

النتيجة:

=== حاسبة بسيطة ===

10 + 5 = 15
10 - 5 = 5
10 × 5 = 50
10 ÷ 5 = 2

---

مثال: دالة مع معالجة الأخطاء

دالة قسمة(أ: صحيح، ب: صحيح) -> نتيجة<صحيح، نص> {
    إذا ب == 0 {
        فشل("لا يمكن القسمة على صفر")
    } وإلا {
        موافق(أ / ب)
    }
}

دالة رئيسية() {
    طباعة("=== معالجة الأخطاء ===")؛
    طباعة()؛

    // حالة ناجحة
    طابق قسمة(10، 2) {
        موافق(نتيجة) => طباعة("✓ 10 ÷ 2 = {}"، نتيجة)،
        فشل(خطأ) => طباعة("✗ خطأ: {}"، خطأ)،
    }

    // حالة خطأ
    طابق قسمة(10، 0) {
        موافق(نتيجة) => طباعة("✓ 10 ÷ 0 = {}"، نتيجة)،
        فشل(خطأ) => طباعة("✗ خطأ: {}"، خطأ)،
    }
}

---

الأوامر الأساسية

الأمر	الوصف
knoz جديد <اسم>	إنشاء مشروع جديد
knoz شغّل	تشغيل المشروع
knoz ابنِ	بناء البرنامج
knoz تحقق	التحقق من الأخطاء بدون بناء
knoz اختبر	تشغيل الاختبارات
knoz --نسخة	عرض النسخة
knoz --مساعدة	عرض المساعدة

---

هيكل المشروع

مشروعي/
├── كنوز.toml         # ملف المشروع
├── مصدر/              # الكود المصدري
│   ├── رئيسي.كنز     # نقطة الدخول
│   └── مكتبة.كنز     # للمكتبات (اختياري)
├── حزم/              # الحزم المثبتة
└── هدف/              # ملفات البناء

---

ملف كنوز.toml

كل مشروع يحتوي على ملف كنوز.toml:

[حزمة]
اسم = "مشروعي"
نسخة = "0.1.0"
وصف = "وصف المشروع"
رخصة = "MIT"

[اعتماديات]
# الحزم المطلوبة

---

إضافة حزمة

# إضافة مكتبة رياضيات
knoz أضف رياضيات_متقدمة

# تثبيت الحزم
knoz ثبّت

استخدام في الكود:

استخدم رياضيات_متقدمة::{جذر_تربيعي، قوة}؛

دالة رئيسية() {
    دع ج = جذر_تربيعي(16.0)؛
    طباعة("الجذر التربيعي لـ 16 = {}"، ج)؛
}

---

الخطوات التالية

الآن بعد أن ثبّت كنوز وكتبت أول برنامج، إليك ما يمكنك فعله:

1. تعلم الأساسيات

المتغيرات والثوابت ←
تعلم كيفية التعامل مع البيانات

الأنواع ←
نظام الأنواع الكامل في كنوز

الدوال ←
كتابة دوال قابلة لإعادة الاستخدام

2. المواضيع المتقدمة

الهياكل ←
إنشاء أنواع بيانات مخصصة

معالجة الأخطاء ←
كتابة كود آمن وموثوق

البرمجة المتزامنة ←
استخدام الخيوط والقنوات

3. أدوات مفيدة

مدير الحزم ←
إدارة الاعتماديات والحزم

---

أمثلة إضافية

حلقة تكرارية

دالة رئيسية() {
    // طالما (while)
    دع متغير عداد = 0؛
    طالما عداد < 5 {
        طباعة("العداد: {}"، عداد)؛
        عداد += 1؛
    }

    // لكل (for)
    لكل رقم في 1..=5 {
        طباعة("الرقم: {}"، رقم)؛
    }
}

مصفوفة وحلقة

دالة رئيسية() {
    دع أسماء = ["أحمد"، "فاطمة"، "علي"، "مريم"]؛

    طباعة("قائمة الأسماء:")؛
    لكل اسم في أسماء {
        طباعة("  - {}"، اسم)؛
    }
}

هيكل بسيط

هيكل شخص {
    اسم: نص،
    عمر: صحيح،
}

نفذ شخص {
    دالة جديد(اسم: نص، عمر: صحيح) -> ذاتي {
        ذاتي { اسم، عمر }
    }

    دالة عرف(&ذاتي) {
        طباعة("أنا {}، عمري {} سنة"، ذاتي.اسم، ذاتي.عمر)؛
    }
}

دالة رئيسية() {
    دع شخص١ = شخص::جديد("أحمد"، 25)؛
    شخص١.عرف()؛
}

---

حل المشاكل الشائعة

لم يتم التعرف على أمر knoz

# تأكد من أن كنوز في PATH
echo $PATH | grep knoz

# أعد تشغيل Terminal أو أعد تحميل الملف
source ~/.bashrc  # أو source ~/.zshrc

خطأ في LLVM

كنوز تحتاج LLVM 20. ثبّته:

# Ubuntu/Debian
wget https://apt.llvm.org/llvm.sh
chmod +x llvm.sh
sudo ./llvm.sh 20

# macOS
brew install llvm@20

الملف بامتداد .كنز لا يُقرأ

تأكد من:

1. استخدام امتداد .كنز وليس .txt
2. حفظ الملف بترميز UTF-8
3. الملف موجود في مجلد مصدر/

---

محرر النصوص

VS Code (موصى به)

# تثبيت إضافة كنوز
code --install-extension knoz-lang.knoz-vscode

الميزات:

• ✓ تلوين الكود
• ✓ الإكمال التلقائي
• ✓ تحديد الأخطاء
• ✓ التنسيق التلقائي

محررات أخرى

يمكنك استخدام أي محرر نصوص يدعم UTF-8:

• Vim/Neovim
• Sublime Text
• Zed
• IntelliJ IDEA

---

الموارد الإضافية

• الدليل الكامل: هذا الموقع!
• صفحة التحميل: تحميل كنوز ←
• الأمثلة: مجلد أمثلة/ في المستودع
• التقارير: GitHub Issues

---

الملخص

تهانينا! الآن أنت جاهز للبدء مع كنوز:

✓ ثبّت كنوز - عبر sh.knoz.dev أو من صفحة التحميل
✓ أنشئ مشروعك الأول - باستخدام knoz جديد
✓ كتبت أول برنامج - “مرحباً بالعالم!”
✓ تعلمت الأوامر الأساسية - شغّل، ابنِ، تحقق

الخطوة التالية: ابدأ بتعلم المتغيرات والثوابت ←