🧮 التعبيرات (Expressions) في لغة نفطه

يوضح هذا الملف كيفية كتابة واستخدام التعبيرات الحسابية والمنطقية في لغة نفطه، بما في ذلك العمليات بين القيم المختلفة مثل: الأعداد، السلاسل، القيم المنطقية، القيم الفارغة، والأنواع المركبة (مثل القوائم والمصفوفات الترابطية).

كما يعرض الفروقات بين الصيغ العادية والصيغ النقطية (dot-notation)، وسلوك العمليات عندما تُستخدم مع سلاسل غير رقمية أو قيم غير مناسبة.

This document demonstrates how to write and use mathematical and logical expressions in the Naftah programming language. It includes operations involving numbers, strings, booleans, null values, and composite structures (lists, sets, maps).

It also explains differences between standard and dot-notation syntax, and how operations behave when used with non-numeric strings or invalid values.

🔢 أمثلة على التعبيرات الحسابية

--- ضرب عددين صحيحين
ثابت ا تعيين 1 * 100

--- ضرب سلسلة عددية برقم باستخدام "ضارب"
ثابت ب تعيين "1" ضارب 100

--- صيغة نقطية للضرب
ثابت ب1 تعيين "1" .ضارب. 100

--- أس مكرر: 2 ** (3 ** 2) = 512
ثابت ا_1 تعيين 2 ** 3 ** 2

--- أس باستخدام سلاسل عددية
ثابت ب_1 تعيين "2" ** 3 ** "2"

✅ العمليات بين القيم المنطقية والأرقام

--- صحيح * 5 = 1 * 5 = 5
ثابت ت تعيين صحيح * 5

--- صيغة نقطية
ثابت ت1 تعيين صحيح .*. 5

--- خاطئ * 5 = 0
ثابت ث تعيين خاطئ ضارب 5

--- فارغ * 3 = 0
ثابت ح تعيين فارغ ضارب 3

✨ التعامل مع السلاسل النصية

--- تكرار الحرف "ب" 3 مرات
ثابت خ تعيين 'ب' * 3

--- ضرب رقم بسلسلة => تكرار السلسلة
ثابت د تعيين 50 ضارب "خ"

🧠 سلوك التعبيرات مع أنواع غير عددية

--- سلسلة فارغة للأس 2 => NaN
"" ** 2

--- فراغ داخل سلسلة
" " ** 2

--- فراغ داخل علامات اقتباس
' ' ** 2

--- سلاسل نصية غير عددية
"مرحبا" ** 2
"مرحبا123" ** 2

🧪 عمليات عنصر-بعنصر على البنى المركبة

--- قائمة ضرب نفسها
[٨٥، ٩٠، ٧٨، ٩٢] * [٨٥، ٩٠، ٧٨، ٩٢]

--- جمع/طرح/قسمة/باقي
[٨٥، ٩٠، ٧٨، ٩٢] + [٨٥، ٩٠، ٧٨، ٩٢]
[٨٥، ٩٠، ٧٨، ٩٢] - [٨٥، ٩٠، ٧٨، ٩٢]
[٨٥، ٩٠، ٧٨، ٩٢] / [٨٥، ٩٠، ٧٨، ٩٢]
[٨٥، ٩٠، ٧٨، ٩٢] % [٨٥، ٩٠، ٧٨، ٩٢]

⚙️ الصيغ النقطية للتعبيرات

--- ضرب نقطي
[٨٥، ٩٠، ٧٨، ٩٢] .*. [٨٥، ٩٠، ٧٨، ٩٢]

--- جمع نقطي
[٨٥، ٩٠، ٧٨، ٩٢] .+. [٨٥، ٩٠، ٧٨، ٩٢]

--- طرح نقطي
[٨٥، ٩٠، ٧٨، ٩٢] .-. [٨٥، ٩٠، ٧٨، ٩٢]

🧮 المقارنات المنطقية

[٨٥، ٩٠، ٧٨، ٩٢] يساوي [٨٥، ٩٠، ٧٨، ٩٢]
[٨٥، ٩٠، ٧٨، ٩٢] لا_يساوي [٨٥، ٩٠، ٧٨، ٩٢]
[٨٥، ٩٠، ٧٨، ٩٢] أكبر_من [٨٥، ٩٠، ٧٨، ٩٢]

📌 التعبيرات بين أرقام ومصفوفات

--- ضرب رقم بقائمة
2 * [٨٥، ٩٠، ٧٨، ٩٢]

--- جمع رقم إلى قائمة
2 + [٨٥، ٩٠، ٧٨، ٩٢]

🧬 التعبيرات على التركيبات (Tuples)

(١، ٢، ٣) + (٤، ٥، ٦)
(١، ٢، ٣) .+. (٤، ٥، ٦)
(١، ٢، ٣) يساوي (١، ٢، ٣)

📁 المصفوفات الترابطية (Dictionaries)

{"عمر": ٢٠} + {"عمر": ٢}
{"معدل": ٨٠} * {"معدل": ٢}

📦 أمثلة على استخدام الاستيراد (Imports)

---* استدعاء دوال مدمجة وإعادة التسمية *---

--- استدعاء دالة الطباعة وإعادة تسميتها محليًا
إجلب إطبع تحت_إسم إطبعلي
إطبعلي("مرحباً أيها العالم!")

--- استدعاء دالة الجمع بعد إعادة التسمية
إجلب إجمع تحت_إسم إجمعلي
إجمعلي(127 , 1)

--- استدعاء دالة الضرب بعد إعادة التسمية
إجلب إضرب تحت_إسم إضربلي
إضربلي(127 , 1)

---* استدعاء دوال ضمن "النداء المؤهّل" (Qualified Call) *---

--- استدعاء دالة و_بتي ضمن الحزمة مع إعادة التسمية
إجلب دوال:الحزم::و_بتي تحت_إسم و_بتي
و_بتي([1 , 2], [3 , 4])

--- استدعاء كامل لدوال الحزم واستخدام دالة منها
إجلب دوال:الحزم تحت_إسم حزم
حزم::و_بتي([1 , 2], [3 , 4])

--- استدعاء عدة دوال من دوال الحزم وإعادة تسمية واحدة منها
إجلب دوال:الحزم::[و_بتي , عكس_الإشارة] تحت_إسم عكس
و_بتي([1 , 2], [3 , 4])
عكس((1 , 2))

🔹 ملاحظات على الاستيراد في نفطه

1. إجلب / استيراد: يستخدم لجلب الدوال أو الحزم أو الكائنات.
2. تحت_إسم / مثل: يسمح بإعادة تسمية الوحدة أو الدالة محليًا لتسهيل الاستخدام.
3. نداء مؤهل (Qualified Call): حزم::دالة يتيح استدعاء دالة محددة ضمن حزمة دون استيراد كل شيء.
4. يمكن استدعاء عدة دوال مع إعادة تسمية واحدة فقط لتجنب التعارضات أو لتبسيط الكود.

🔀 عمليات الإزاحة البتّية (Bitwise Shift Operations)

تُستخدم عمليات الإزاحة لتحريك البتّات يمينًا أو يسارًا داخل القيمة العددية. يدعم Naftah أعدادًا غير محدودة الحجم طالما كانت أعدادًا صحيحة.

⬅️ الإزاحة إلى اليسار (Shift Left)

🔹 الصيغة الرمزية

64 << 2
1073741824 << 2
1 << 100

🔹 الصيغة اللفظية

64 إزاحة_يسار 2
1073741824 إزاحة_يسار 2
1 إزاحة_يسار 100

🧠 الشرح

• كل إزاحة لليسار تعادل الضرب في 2ⁿ
• تدعم أعدادًا ضخمة جدًا بدون فقدان دقة

أمثلة ناتج:

64 << 2  → 256
1 << 100 → 1267650600228229401496703205376

➡️ الإزاحة إلى اليمين (Shift Right – Signed)

🔹 الصيغة الرمزية

128 >> 2
32768 >> 2
9223372036854775808 >> 2

🔹 الصيغة اللفظية

128 إزاحة_يمين 2
32768 إزاحة_يمين 2
9223372036854775808 إزاحة_يمين 2

🧠 الشرح

• تعادل القسمة الصحيحة على 2ⁿ
• تحافظ على الإشارة (في حال دعم الأعداد السالبة)

مثال:

128 >> 2 → 32

➡️➡️ الإزاحة إلى اليمين غير الموقعة (Unsigned Shift Right)

🔹 الصيغة الرمزية

128 >>> 2
2147483648 >>> 2
9223372036854775808 >>> 2

🔹 الصيغة اللفظية

128 إزاحة_يمين_غير_موقعة 2
2147483648 إزاحة_يمين_غير_موقعة 2
9223372036854775808 إزاحة_يمين_غير_موقعة 2

🧠 الشرح

• إزاحة يمين بدون اعتبار الإشارة
• مفيدة في العمليات منخفضة المستوى (Low-level / Bit masking)

⚠️ القيود والأخطاء

❌ الأعداد العشرية غير مدعومة

أي محاولة لاستخدام الإزاحة مع عدد عشري تؤدي إلى خطأ لغوي (Bug Error):

340282346638528859811704183484516925440,000000 << 2

❗ السبب:

عمليات الإزاحة تعمل فقط على الأعداد الصحيحة (Integer / BigInteger)

🧠 ملاحظات مهمة

• التعبيرات يمكن أن تكون بين نفس النوع أو بين أنواع مختلفة مثل رقم وسلسلة.
• عند استخدام سلاسل نصية غير رقمية في عمليات عددية، النتيجة غالبًا قيمة_غير_رقمية (NaN).
• فارغ و خاطئ يتم التعامل معهما كـ 0، وصحيح كـ 1.
• الصيغ النقطية (.*., .+., …) مفيدة جدًا لتطبيق العمليات عنصرًا بعنصر على البنى المركبة.
• العمليات على التركيبات والمصفوفات الترابطية تتم بناءً على المفاتيح أو ترتيب العناصر.
• يمكن دمج التعبيرات ببعضها في تعبيرات مركبة معقدة.