--- SPDX-License-Identifier: Apache-2.0
--- Copyright © The Naftah Project Authors

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

- الحلقات العددية المتزايدة والمتناقصة
- الحلقات مع خطوات مخصصة (step)
- التحكم في تدفق الحلقة باستخدام "اكسر" و"تابع"
- الحلقات المتداخلة
- الحلقات المسماة لكسر/تخطي حلقة معينة بدقة
- التكرار على القوائم والمصفوفات باستخدام `من` و `داخل`
- التكرار على الكائنات باستخدام `من_بين`
- التكرار على الكائنات المعقدة باستخدام `أ؛ب:ت`
*---

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

--- حلقة تنازلية بخطوة 2
كرر_حلقة أ تعيين 1000 تنازليا 1 خطوة 2 إفعل {
    إطبع(أ)  --- العد التنازلي بخطوتين: 1000، 998، ...
}
أنهي

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

--- تكرار على قائمة مركبة من أنواع مختلفة
كرر_حلقة أ من (1؛"نخيل"؛3،2؛'س'؛خاطئ؛حقيقي؛لاشيء؛(سلسلة_ثمانية_بت "سراب")؛ليس_عددي) إفعل {
    إطبع(أ)  --- العناصر متنوعة: أرقام، نصوص، منطقية، إلخ
}
أنهي

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

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

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

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