🌀 التحكم في تدفق البرنامج في لغة نفطه (Control Flow)

هذا الملف يشرح كيفية استخدام أوامر التحكم في تدفق البرنامج في لغة نفطه، التي تشمل: if مع elseif و else، حلقات التكرار المختلفة (for, foreach, while, repeat-until)، تعليمات الحالة case، وأسلوب التعامل مع الأخطاء والخيارات عبر try مع أنماط ok/error أو some/none.
يحتوي الملف على تعريفات تفصيلية مع أمثلة توضيحية لكل بنية.


This file explains control flow statements in Naftah language including conditional statements (if, elseif, else), loops (for, foreach, while, repeat-until), case statements, and error/option handling with try blocks using ok/error or some/none patterns.
It provides detailed definitions and illustrative examples.


🔀 جمل الشرط (If Statements)

صيغة شرطية تسمح بتنفيذ كتلة برمجية عند تحقق شرط معين، مع إمكانية إضافة عدة شروط بديلة وكتلة بديلة أخيرة.

--- تعريف متغيرين بقيم ابتدائية
متغير أ تعيين ١
متغير ب تعيين 4

---* تحقق من قيمة مجموع "أ + ب" باستخدام تعبير شرطي يحتوي على ثلاث حالات:
   - إذا كان الناتج أكبر من 10، اطبع رسالة بذلك.
   - إذا كان الناتج أصغر من 10، اطبع رسالة مناسبة.
   - إذا كان الناتج يساوي 10، اطبع رسالة مساوية.
*---
إذا أ زائد ب أكبر_من ١٠ إذن {
  --- في حال تحقق الشرط: مجموع أ + ب أكبر من 10
إطبع("أ زائد ب أكبر من 10")
} غير_ذلك_إذا أ زائد ب أصغر_من ١٠ إذن {
  --- في حال لم يتحقق الشرط الأول، وتحقق هذا الشرط: المجموع أصغر من 10
إطبع("أ زائد ب أصغر مين 10")
} غير_ذلك {
  --- في حال لم يتحقق أي من الشرطين السابقين، أي أن أ + ب = 10
إطبع("أ زائد ب يساوي 10")
}
أنهي

📌 تعبيرات شرطية ثلاثية (Ternary Expressions)

تعبير مختصر يسمح بالاختيار بين قيمتين بناءً على شرط:

شرط ؟ قيمة_إذا_صحيح : قيمة_إذا_خطأ أنهي

أمثلة:

--- تعبير ثلاثي: إذا كانت أ صحيحة، أ، وإلا ب
أ ؟ أ : ب أنهي

--- تعبير ثلاثي: إذا كانت القيمة غير رقمية، أ، وإلا ب
قيمة_غير_رقمية ؟ أ : ب أنهي

--- تعبير ثلاثي: إذا كانت القيمة فارغة، أ، وإلا ب
فارغ ؟ أ : ب أنهي

--- تعبير ثلاثي مركب مع شرط داخل قوس
(أ زائد ب أكبر_من ١٠) ؟ أ : ب أنهي

--- تعبير ثلاثي متداخل مع تعبير ثلاثي آخر
(أ زائد ب أصغر_من ١٠) ؟ (أ ؟ أ : ب) : أ أنهي

📌 تعبير nullish (Nullish Coalescing)

يستخدم لاختيار القيمة الأولى غير null أو undefined (أو القيمة الفارغة حسب التعريف) بين قيمتين:

قيمة_1 ؟؟ قيمة_2 أنهي

تعريف متغيرات إضافية لاستخدامها مع nullish:

متغير ت تعيين 2
متغير ث تعيين 3
متغير ج تعيين 5

أمثلة:

--- تعبير nullish: إذا كانت أ غير nullish، استخدم أ، وإلا ب
أ ؟؟ ب أنهي

--- تعبير nullish: إذا كانت القيمة فارغة، استخدم ب
فارغ ؟؟ ب أنهي

--- تعبير nullish: إذا كانت القيمة غير رقمية، استخدم أ
قيمة_غير_رقمية ؟؟ أ أنهي

--- تعبير nullish متداخل
أ ؟؟ ب ؟؟ ت أنهي
أ ؟؟ ب ؟؟ ت ؟؟ ث أنهي
أ ؟؟ ب ؟؟ ت ؟؟ ث ؟؟ ج أنهي

🔄 حلقات التكرار (Loops)

—* هذا الملف يشرح كيفية استخدام الحلقات (loops) في لغة نفطه، ويغطي:


1. حلقات رقمية بترتيب تصاعدي أو تنازلي (Index-based loops)

تكرار يبدأ من قيمة مبدئية إلى قيمة نهائية، مع إمكانية تحديد الخطوة والاتجاه (تصاعدي أو تنازلي):

--- حلقة تكرارية من 1 إلى 5
كرر_حلقة أ تعيين 1 إلى 5 إفعل {
    إطبع(أ)  --- طباعة قيمة المتغير أ في كل دورة
}
أنهي

--- حلقة تنازلية من 10 إلى 1
كرر_حلقة أ تعيين 10 تنازليا 1 إفعل {
    إطبع(أ)  --- العد تنازلي من 10 إلى 1
}
أنهي

--- حلقة بكسر مبكر عند أ == 2
كرر_حلقة أ تعيين 1 إلى 3 إفعل {
    إذا أ == 2 إذن {
        اكسر  --- إنهاء الحلقة عند وصول أ إلى 2
    }
    أنهي
}
غير_ذلك {
    إطبع("لم يتم كسر الحلقة")  --- ينفذ فقط إذا لم تُكسر الحلقة
}
أنهي

--- استخدام "تابع" لتخطي دورة عند أ == 3
كرر_حلقة أ تعيين 1 إلى 5 إفعل {
    إذا أ == 3 إذن {
        تابع  --- تخطي الطباعة عند 3
    }
    أنهي
    إطبع(أ)
}
أنهي

--- استخدام خطوة مخصصة 10
كرر_حلقة أ تعيين 1 إلى 500 خطوة 10 إفعل {
    إطبع(أ)  --- يطبع: 1، 11، 21، ...
}
أنهي

--- خطوة عشرية كخطوة 0،1
كرر_حلقة أ تعيين 1 إلى 2 خطوة 0،1 إفعل {
    إطبع(أ)  --- 1، 1.1، 1.2، ...
}
أنهي

2. الحلقات المتداخلة (Nested loops)

يمكن وضع حلقة داخل أخرى:

--- حلقة متداخلة (أ × ب)
كرر_حلقة أ تعيين 1 إلى 3 إفعل {
    كرر_حلقة ب تعيين 1 إلى 2 إفعل {
        إطبع("أ يساوي ${أ} - ب يساوي ${ب}")
    }
    أنهي
}
أنهي

--- استخدام "اكسر" في حلقة داخلية عند ب == 3
كرر_حلقة أ تعيين 1 إلى 3 إفعل {
    كرر_حلقة ب تعيين 1 إلى 5 إفعل {
        إذا ب == 3 إذن {
            اكسر  --- كسر الحلقة الداخلية فقط
        }
        أنهي
        إطبع("أ يساوي ${أ} - ب يساوي ${ب}")
    }
    أنهي
}
أنهي

--- حلقة متداخلة مع كسر عام باستخدام وسم حلقة
حلقة:
كرر_حلقة أ تعيين 1 إلى 5 إفعل {
    كرر_حلقة ب تعيين 1 إلى 5 إفعل {
        إذا ((أ == 2) و (ب == 2)) إذن {
            اكسر  --- كسر الحلقة المعنونة "حلقة"
        }
        أنهي
        إطبع("أ يساوي ${أ} - ب يساوي ${ب}")
    }
    أنهي
}
أنهي

--- حلقات متعددة المستوى مع كسر وتسميات
الخارجي:
كرر_حلقة أ تعيين 1 إلى 5 إفعل {
    الأوسط:
    كرر_حلقة ب تعيين 1 إلى 5 إفعل {
        الداخلي:
        كرر_حلقة ت تعيين 1 إلى 5 إفعل {
            إذا ((أ == 2) و (ب == 2) و (ت == 2)) إذن {
                إطبع("كسر الخارجي : أ يساوي ${أ} - ب يساوي ${ب} - ت يساوي ${ت}")
                اكسر الخارجي
            }
            أنهي
            إذا ت == 2 إذن {
                إطبع("تابع الداخلي : أ يساوي ${أ} - ب يساوي ${ب} - ت يساوي ${ت}")
                تابع
            }
            أنهي
            إطبع("أ يساوي ${أ} - ب يساوي ${ب} - ت يساوي ${ت}")
        }
        أنهي
    }
    أنهي
}
أنهي

3. حلقات foreach للتكرار على عناصر مجموعة أو قائمة أو كائنات

التكرار على قائمة (List):

كرر_حلقة عنصر من ["واحة"، "نخيل", "ينبوع"] إفعل {
    إطبع(عنصر)  --- طباعة كل عنصر في القائمة
}
أنهي

التكرار على مصفوفة (Array) باستخدام داخل:

كرر_حلقة أ داخل [1؛2؛3؛4] إفعل {
    إطبع(أ)  --- المرور على كل عنصر في المصفوفة
}
أنهي

التكرار على قائمة مع فهرس وقيمة:

كرر_حلقة فهرس؛ قيمة ضمن {"واحة", "نخيل", "ينبوع", "ظل"} إفعل {
    إطبع("${فهرس} - ${قيمة}")  --- الفهرس والقيمة لكل عنصر
}
أنهي

التكرار على قاموس (Object) بمفتاح وقيمة باستخدام من_بين:

كرر_حلقة مفتاح: قيمة من_بين {"اسم": "أحمد", "عمر": ٢٠, "معدل": ٨٨} إفعل {
    إطبع("${مفتاح} - ${قيمة}")  --- عرض المفتاح والقيمة
}
أنهي

التكرار على كائن مع مفاتيح وقيم وأسماء متغيرة مخصصة:

كرر_حلقة فهرس؛ مفتاح: قيمة داخل {
    متغير الماركة تعيين "بيجو",
    متغير الموديل تعيين 2021,
    متغير اللون تعيين "أبيض"
} إفعل {
    إطبع("${فهرس} - ${مفتاح} - ${قيمة}")  --- عرض الفهرس، المفتاح، والقيمة
}
أنهي

4. أخطاء شائعة مع التسمية في الكسر (break)

حلقة:
كرر_حلقة أ تعيين 1 إلى 5 إفعل {
    حلقة_غير_معرّفة:
    كرر_حلقة ب تعيين 1 إلى 5 إفعل {
        إذا ((أ == 2) و (ب == 2)) إذن {
            اكسر حلقة_غير_معرّفة  --- سيولد خطأ، لأن التسمية غير معرفة
        }
        أنهي
        إطبع("أ يساوي ${أ} - ب يساوي ${ب}")
    }
    أنهي
}
أنهي

5. حلقات واسعة النطاق وأداء

--- حلقة طويلة بدون حد واقعي (2147483647 = max int)
كرر_حلقة أ تعيين 1 إلى 2147483647 إفعل {
    إطبع(أ)  --- قد تؤدي إلى استهلاك عالي للموارد
}
أنهي

بهذا الشكل يمكنك التحكم الكامل في الحلقات في لغة نفطه، من الحلقات البسيطة العددية إلى الحلقات المعقدة والمتداخلة مع إدارة دقيقة لتدفق التنفيذ.


أكيد! هنا شرح مفصل لحلقة while في لغة نفطه بأسلوب مشابه لحلقة for اللي شرحتها لك سابقًا، مع أمثلة واقعية وتفصيلية.


🔄 حلقة while (بينما)

مفهوم حلقة while:


بناء الجملة في نفطه

بينما (الشرط) افعل {
    --- تعليمات التكرار طالما الشرط صحيح
}
أنهي

أمثلة تفصيلية مع شرح


1. طباعة الأعداد من 1 إلى 10 باستخدام while

متغير أ تعيين 1

بينما أ أصغر_أو_يساوي 10 افعل {
    إطبع(أ) أنهي
    زد أ
}
أنهي

2. التوقف المبكر باستخدام اكسر

متغير أ تعيين 1

بينما أ أصغر_من 20 افعل {
    إذا أ == 5 إذن {
        اكسر  --- توقف الحلقة فورًا عند وصول أ إلى 5
    }
    إطبع(أ) أنهي
    زد أ
}
أنهي

3. تخطي خطوة باستخدام تابع

متغير أ تعيين 0

بينما أ أصغر_من 10 افعل {
    زد أ
    إذا أ == 3 إذن {
        تابع  --- تخطي طباعة الرقم 3
    }
    إطبع(أ)
}
أنهي

4. حلقة while متداخلة مع for loop (كرر_حلقة)

متغير أ تعيين 1

بينما أ أصغر_أو_يساوي 3 افعل {

    متغير ب تعيين 1

    بينما ب أصغر_أو_يساوي 2 افعل {
        إطبع("أ = ${أ}, ب = ${ب}") أنهي
        زد ب
    }
    
    زد أ
}
أنهي

5. استخدام while مع شرط معقد

متغير أ تعيين 10
متغير ب تعيين 20

بينما (أ أصغر_من ب) و (ب أصغر_من 30) افعل {
    إطبع("أ = ${أ}، ب = ${ب}") أنهي
    زد أ أنهي
    نقص ب
}
أنهي

نصائح


أكيد! هنا شرح مفصل وموسع لحلقة repeat-until (كرر … حتى) مع أمثلة واضحة وتفصيلية بلغة نفطه، بأسلوب منظم وشامل يشبه الأمثلة اللي أرسلتها:


🔄 حلقة repeat-until (كرر … حتى)

مفهوم حلقة repeat-until:


البناء العام في نفطه

كرر {
    --- تعليمات التكرار
} حتى (الشرط)

أمثلة تفصيلية مع شرح


1. طباعة الأعداد من 1 حتى أكبر من 9

متغير أ تعيين ١

كرر {
    إطبع(أ) أنهي
    زد أ
}
حتى أ أكبر_من ٩
أنهي

الشرح:


2. حلقة متداخلة مع بينما و كرر ... حتى

كرر_حلقة أ تعيين 1 إلى 5 إفعل {

    متغير ت تعيين ١

    بينما ت أصغر_من ١٠ افعل {

        إطبع(ت) أنهي
        زد ت

        متغير ي تعيين ١

        كرر {
            إطبع(ي) أنهي
            زد ي
        }
        حتى ي أكبر_من ٩
        أنهي
    }
    أنهي

    إطبع(أ)
}
أنهي

الشرح:


3. مثال مع كسر مبكر (باستخدام اكسر)

متغير أ تعيين ١

كرر {
    إطبع(أ)
    إذا أ == ٥ إذن {
        اكسر  --- التوقف فورًا عند وصول أ إلى 5
    }
    زد أ
}
حتى أ أكبر_من ٩
أنهي

4. مثال مع تخطي خطوة (باستخدام تابع)

متغير أ تعيين ٠

كرر {
    زد أ
    إذا أ == ٣ إذن {
        تابع  --- تخطي طباعة الرقم 3
    }
    إطبع(أ)
}
حتى أ أكبر_من ٩
أنهي

5. استخدام شرط مركب في حتى

متغير أ تعيين ١
متغير ب تعيين ١٠

كرر {
    إطبع("أ = ${أ}، ب = ${ب}") أنهي
    زد أ أنهي
    زد ب أنهي
}
حتى (أ أكبر_من ٩) أو (ب أكبر_من ٢٠)
أنهي

نصائح


أكيد! هنا إعادة صياغة لشرح جملة الحالة (Case Statement) في لغة نفطه بأسلوب مشابه لمثال الـ switch المفصل الذي أرسلتَه:


🎯 جملة الحالة (Case Statement)

جملة الحالة تسمح بالاختيار بين عدة كتل تنفيذية بناءً على قيمة تعبير معين. يمكن استخدام عدة قيم للحالة الواحدة، بالإضافة إلى حالة افتراضية وإلا تُنفذ إذا لم تتطابق أي حالة.


البناء العام

حسب (التعبير) من {
    قيمة1، قيمة2: {
        --- تعليمات للحالتين قيمة1 وقيمة2
    }
    قيمة3: {
        --- تعليمات للحالة قيمة3
    }
    وإلا {
        --- تعليمات افتراضية للحالات غير المتطابقة
    }
}

مثال مفصل مع دعم القيم المتعددة والشروط:

--- تعريف متغير أ وتعيينه بالقيمة ١
متغير أ تعيين ١

--- تعريف متغير ب وتعيينه بالقيمة ٤
متغير ب تعيين ٤

--- تعريف متغير ت وتعيين ناتج جمع أ وب
متغير ت تعيين أ زائد ب

--- بداية جملة الحالة حسب قيمة ت
حسب (ت) من {

    --- الحالات التي تشمل 15، 2، 3 أو تحقق شرط "ت أكبر من ١٠"
    15؛ 2؛ 3؛ ت أكبر_من ١٠: {
        إطبع("أ زائد ب أكبر من 10")
    }

    --- الحالات التي تشمل النص "15"، القيمة المنطقية خاطئ، شرط "ت أصغر من ١٠" أو 5
    "15"؛ خاطئ؛ ت أصغر_من ١٠؛ 5: {
        إطبع("أ زائد ب أصغر من 10")
    }

    --- الحالة الافتراضية لأي قيمة أخرى
    وإلا {
        إطبع("أ زائد ب يساوي 10")
    }
}

شرح المثال:


أكيد! إليك شرحًا مفصلًا ومنسقًا لآلية التعامل مع الأخطاء والخيارات باستخدام جملة حاول (try) في لغة نفطه، مع أمثلة تطبيقية توضح التعامل مع حالات نجاح/فشل وبعض/معدوم بطريقة مشابهة لمحتواك:


🛠️ معالجة الأخطاء والخيارات (Try Statement)

في لغة نفطه، تعبير حاول يُستخدم لتنفيذ تعبير قد يفشل أو يكون له قيمة محتملة، مع التعامل المدمج لحالات النجاح والفشل أو وجود/عدم وجود قيمة.


1. التعامل مع الحالات نجاح و فشل

حاول (تعليمات_قد_تفشل) {
    نجاح(النتيجة) -> {
        --- تعليمات عند النجاح
    }
    فشل(السبب) إفعل {
        --- تعليمات عند الخطأ
    }
}

2. التعامل مع الحالات بعض و معدوم

حاول (خيار_محتمل) {
    بعض(القيمة) -> {
        --- تعليمات عند وجود القيمة
    }
    معدوم إفعل {
        --- تعليمات عند عدم وجود القيمة
    }
}

أمثلة تطبيقية مفصلة


مثال 1: محاولة تنفيذ قيمة ثابتة ناجحة

حاول(1) {
    نجاح(أ) -> إطبع(أ)       --- يطبع 1
    فشل(ب) إفعل إطبع(ب)     --- لن يُنفذ
}

مثال 2: محاولة قسمة على صفر - تسبب خطأ

حاول(1 قسمة 0) {
    نجاح(أ) -> إطبع(أ)       --- لن يُنفذ
    فشل(ب) إفعل إطبع(ب)     --- يطبع رسالة الخطأ (قسمة على صفر)
}

مثال 3: تداخل محاولات داخل فشل

حاول(1 قسمة 0) {
    نجاح(أ) -> إطبع(أ)       --- لا يُنفذ
    فشل(ب) إفعل {
        إطبع(ب)              --- طباعة الخطأ
        حاول(1) {
            نجاح(أ) -> إطبع(أ) --- يطبع 1
            فشل(ب) إفعل إطبع(ب)
        }
    }
}

مثال 4: التعامل مع كائن (Object)

متغير بلدة تعيين {
    متغير الاسم تعيين "نفطه",
    متغير المدينة تعيين "مدينة",
    متغير عدد_الأحياء تعيين 5
}

حاول(بلدة) {
    نجاح(أ) -> {
        ثابت الاسم تعيين بلدة["الاسم"]
        ثابت المدينة تعيين أ["المدينة"]
        ثابت عدد_الأحياء تعيين أ["عدد_الأحياء"]
        إطبع("الاسم = ${الاسم}، المدينة = ${المدينة}، عدد_الأحياء = ${عدد_الأحياء}")
    }
    فشل(ب) إفعل إطبع(ب)
}

مثال 5: التعامل مع قائمة متداخلة

متغير قائمة_1 تعيين [١٠, [٩, [٨, [٧, [٦, [٥, [٤, [٣, [٢, ١]]]]]]]]]

حاول(قائمة_1) {
    نجاح(أ) -> {
        ثابت قائمة_1_0 تعيين أ[0]
        ثابت قائمة_1_1 تعيين أ[1]
        ثابت قائمة_1_1_0 تعيين أ[1][0]
        إطبع("قائمة_1_0 = ${قائمة_1_0}، قائمة_1_1 = ${قائمة_1_1}، قائمة_1_1_0 = ${قائمة_1_1_0}")
    }
    فشل(ب) إفعل إطبع(ب)
}

مثال 6: التعامل مع خيارات (Option) - بعض ومعدوم

حاول(1) {
    بعض(أ) -> إطبع(أ)          --- يطبع 1
    معدوم إفعل إطبع("لاشيء.")
}

حاول(لاشيء) {
    بعض(أ) -> إطبع(أ)          --- لا يُنفذ
    معدوم إفعل إطبع("لاشيء.")  --- يطبع "لاشيء."
}

أمثلة أخرى للقيم الغائبة أو غير الصالحة:

حاول(باطل) { بعض(أ) -> إطبع(أ) معدوم إفعل إطبع("لاشيء.") }
حاول(فارغ) { بعض(أ) -> إطبع(أ) معدوم إفعل إطبع("لاشيء.") }
حاول(ليس_رقم) { بعض(أ) -> إطبع(أ) معدوم إفعل إطبع("لاشيء.") }
حاول(قيمة_غير_رقمية) { بعض(أ) -> إطبع(أ) معدوم إفعل إطبع("لاشيء.") }
حاول(رقم_غير_صالح) { بعض(أ) -> إطبع(أ) معدوم إفعل إطبع("لاشيء.") }
حاول(غير_عددي) { بعض(أ) -> إطبع(أ) معدوم إفعل إطبع("لاشيء.") }
حاول(ليس_عددي) { بعض(أ) -> إطبع(أ) معدوم إفعل إطبع("لاشيء.") }

📝 ملخص بناء الجمل

البنية الوصف شكل التعريف مثال مختصر
ifStatement شرط مع elseif و else IF expr THEN block (ELSEIF expr THEN block)* (ELSE block)? إذا (x > 0) نفذ {...} وإلا {...}
forStatement حلقة for (index-based أو foreach) FOR i := 1 TO 10 DO block (ELSE block)? أو FOR val IN expr DO block لـ i := 1 إلى 10 نفذ {...}
whileStatement حلقة شرطية WHILE expr DO block; بينما (شرط) نفذ {...}
repeatStatement حلقة تنفذ ثم تكرر حتى الشرط REPEAT block UNTIL expr; كرر {...} حتى (شرط)
caseStatement جملة حالة متعددة القيم CASE expr OF (labels: block)+ (ELSE block)?; حسب (x) من { 1: {...} 2: {...} }
tryStatement محاولة مع حالات ok/error أو some/none TRY(expr) { OK(id) DO block ERROR(id) DO block } أو TRY(expr) { SOME(id) DO block NONE DO block } كما في الأمثلة أعلاه

## 📁 ملفات مرتبطة * [Home - الرئيسية](./../../../README.md) * [🔑 الكلمات المفتاحية - Keywords](./01_keywords.md) * [🧱 الأنواع الأولية و الثوابت و المتغيرات - Primitive Types And Variables](./02_primitives_and_variables.md) * [📚 بُنى المعطيات - Collections](./03_collections.md) * [🧮 التعبيرات - Expressions](./04_expressions.md) * [🔢 الأعداد بأنظمة العد - Radix Numbers](./05_radix_numbers.md) * [📦 تعريف الكائنات - Objects](./06_objects.md) * [⚙️ الدوال في لغة نفطه - Functions](./08_functions.md) * [⚙️ التوافق مع Java (Java Interop) في لغة نفطه - Java Interop](./09_java_interop.md) * [⚡ التعامل مع التزامن في نفطه – Concurrency](./10_concurrency.md) * [⏱️ الزمن والنقاط الزمنية في نفطه – Temporal](./11_temporal.md) ---