💎 لغة ياقوت (Yaqout Language)

أول لغة برمجة عربية احترافية مبنية على Lua 5.5

---

📋 جدول المحتويات

• نظرة عامة
• المميزات الرئيسية
• العيوب والقيود
• التثبيت والبدء
• أمثلة برمجية
• المكتبات القياسية
• جدول الكلمات المفتاحية
• مقارنة مع اللغات الأخرى
• الأسئلة الشائعة
• المساهمة
• الترخيص

---

🌟 نظرة عامة

ياقوت هي لغة برمجة نصية (Scripting Language) قوية وسريعة، تم تطويرها لتكون النسخة العربية الكاملة من لغة Lua الشهيرة. تهدف ياقوت إلى تمكين المبرمجين العرب من كتابة الأكواد بروح لغتهم الأصلية، مع الحفاظ على الأداء العالي والمرونة التي تتميز بها Lua.

لماذا ياقوت؟

• 🎓 تعليمية: مثالية لتعليم البرمجة للمبتدئين العرب
• 🎮 عملية: يمكن استخدامها في تطوير الألعاب والتطبيقات
• ⚡ سريعة: تحافظ على أداء Lua المشهور
• 🌍 مفتوحة المصدر: مجانية للاستخدام والتعديل

---

✨ المميزات الرئيسية

1. 🔤 عربية بالكامل

كلمات مفتاحية عربية تجعل الكود قابلاً للقراءة بسهولة:

إذا العمر >= 18 إذن
    اطبع("أنت بالغ")
وإلا
    اطبع("أنت قاصر")
نهاية

2. 📛 دعم اليونيكود

إمكانية تسمية المتغيرات والدوال بحروف عربية أصيلة:

محلي اسم_المستخدم = "أحمد"
محلي عمر_المستخدم = 25

دالة حساب_العمر_بالأيام(سنوات)
    ارجع سنوات * 365
نهاية

3. 📚 مكتبات قياسية معربة

جميع وظائف الرياضيات، النصوص، الجداول، والنظام متوفرة بأسماء عربية:

محلي الجذر = رياضيات.جذر(16)  -- 4
محلي النص = نصوص.عكس("مرحبا")  -- "ابحرم"
جدول.إدراج(قائمتي, "عنصر جديد")

4. 📁 امتدادات ملفات مخصصة

دعم ملفات .ياقوت و .yq:

yaqout.exe برنامجي.yq
yaqout.exe تطبيق.ياقوت

5. ⚡ خفيفة وسريعة

تحافظ على نفس محرك Lua السريع والفعال:

• حجم الملف التنفيذي: ~200KB
• استهلاك الذاكرة: منخفض جداً
• سرعة التنفيذ: قريبة من C

6. 🎨 دعم VS Code

إضافة (Extension) تلوين الكود وأيقونة رسمية للغة:

• تلوين الكلمات المفتاحية العربية
• دعم الإكمال التلقائي
• أيقونة مخصصة لملفات .yq

7. 📦 مكتبات متقدمة

دعم ياقوت.ملفات و ياقوت.ويب:

استدعي("library.yq")
ياقوت.ملفات.كتابة("نص.txt", "مرحباً")
ياقوت.ويب.جلب("https://example.com")

8. 🔄 التوافق مع Lua

يمكنك استخدام الكلمات الإنجليزية جنباً إلى جنب مع العربية:

local x = 10
محلي ص = 20
if x > ص then
    اطبع("x أكبر")
end

---

⚠️ العيوب والقيود

1. 🔧 التوافق مع المكتبات الخارجية

• المكتبات المكتوبة بـ C قد لا تدعم أسماء الدوال العربية
• يُنصح باستخدام أسماء إنجليزية للواجهات الخارجية

2. 📝 التحرير والبيئات

• بعض المحررات القديمة لا تدعم الكتابة من اليمين لليسار
• قد تواجه مشاكل مع بعض الخطوط

3. 🌐 الترميز

• يجب حفظ الملفات بترميز UTF-8
• بعض الطرفيات تحتاج إعداداً خاصاً لعرض العربية

4. 📚 التوثيق

• التوثيق لا يزال قيد التطوير
• المجتمع العربي أصغر من مجتمع Lua الإنجليزي

5. 🔍 البحث والمساعدة

• صعوبة البحث عن حلول للمشاكل باللغة العربية
• معظم موارد Lua بالإنجليزية

---

🚀 التثبيت والبدء

التحميل السريع (Windows)

# 1. حمّل ملف yaqout.exe من صفحة الإصدارات
# 2. ضعه في مجلد وأضفه للـ PATH
# 3. افتح الطرفية واختبر:
yaqout.exe -v

التجميع من المصدر

# متطلبات: GCC أو MinGW
gcc -O2 -std=c99 -DLUA_USE_WINDOWS -o yaqout.exe ^
    lua.c lapi.c lcode.c lctype.c ldebug.c ldo.c ldump.c ^
    lfunc.c lgc.c llex.c lmem.c lobject.c lopcodes.c ^
    lparser.c lstate.c lstring.c ltable.c ltm.c lundump.c ^
    lvm.c lzio.c lauxlib.c lbaselib.c lcorolib.c ldblib.c ^
    liolib.c lmathlib.c loslib.c lstrlib.c ltablib.c ^
    lutf8lib.c loadlib.c linit.c -lm

تثبيت إضافة VS Code

# شغّل سكربت التثبيت
install_extension.bat

---

💻 أمثلة برمجية

مثال 1: ترحيب بسيط

-- برنامج ترحيب بسيط
محلي الاسم = "زائر"

دالة ترحيب(نص)
    اطبع("أهلاً بك يا " .. نص .. " في لغة ياقوت!")
نهاية

ترحيب(الاسم)

مثال 2: حساب المتوسط

-- حساب متوسط درجات الطلاب
محلي درجات = {85, 92, 78, 95, 88}
محلي المجموع = 0

لكل ي, درجة في أزواج(درجات) افعل
    المجموع = المجموع + درجة
نهاية

محلي المتوسط = المجموع / #درجات
اطبع("متوسط الدرجات: " .. المتوسط)

مثال 3: القائمة المتكررة

-- طباعة جدول الضرب
دالة جدول_الضرب(رقم)
    اطبع("جدول ضرب العدد " .. رقم .. ":")
    لكل ي = 1, 10 افعل
        محلي النتيجة = رقم * ي
        اطبع(رقم .. " × " .. ي .. " = " .. النتيجة)
    نهاية
نهاية

جدول_الضرب(7)

مثال 4: التعامل مع الجداول

-- إنشاء كائن طالب
محلي طالب = {
    اسم = "سارة",
    عمر = 20,
    تخصص = "هندسة البرمجيات",
    درجات = {
        رياضيات = 95,
        برمجة = 98,
        فيزياء = 88
    }
}

-- دالة لحساب المعدل
دالة احسب_المعدل(ط)
    محلي مجموع = 0
    محلي عدد = 0
    لكل مادة, درجة في أزواج(ط.درجات) افعل
        مجموع = مجموع + درجة
        عدد = عدد + 1
    نهاية
    ارجع مجموع / عدد
نهاية

اطبع("اسم الطالب: " .. طالب.اسم)
اطبع("المعدل: " .. احسب_المعدل(طالب))

مثال 5: التعامل مع الملفات

استدعي("library.yq")

-- كتابة ملف
ياقوت.ملفات.كتابة("مذكرة.txt", "هذه مذكرتي الشخصية")

-- قراءة ملف
محلي ملف = دخل_خرج.فتح("مذكرة.txt", "r")
إذا ملف إذن
    محلي محتوى = ملف:قراءة("*all")
    اطبع(محتوى)
    ملف:إغلاق()
نهاية

---

📚 المكتبات القياسية

📊 مكتبة الرياضيات (رياضيات)

الدالة	الوصف	مثال
رياضيات.جذر(س)	الجذر التربيعي	رياضيات.جذر(16) → 4
رياضيات.جيب(س)	جيب الزاوية (Sin)	رياضيات.جيب(0) → 0
رياضيات.جتا(س)	جيب تمام (Cos)	رياضيات.جتا(0) → 1
رياضيات.ظل(س)	ظل الزاوية (Tan)	رياضيات.ظل(0) → 0
رياضيات.أرض(س)	تقريب للأسفل	رياضيات.أرض(3.7) → 3
رياضيات.سقف(س)	تقريب للأعلى	رياضيات.سقف(3.2) → 4
رياضيات.قيمة_مطلقة(س)	القيمة المطلقة	رياضيات.قيمة_مطلقة(-5) → 5
رياضيات.أقصى(...)	أكبر قيمة	رياضيات.أقصى(1,5,3) → 5
رياضيات.أدنى(...)	أصغر قيمة	رياضيات.أدنى(1,5,3) → 1
رياضيات.عشوائي(م,ن)	رقم عشوائي	رياضيات.عشوائي(1,100)
رياضيات.ط	قيمة π	3.14159...

📝 مكتبة النصوص (نصوص)

الدالة	الوصف	مثال
نصوص.طول(س)	طول النص	نصوص.طول("مرحبا") → 5
نصوص.عكس(س)	عكس النص	نصوص.عكس("abc") → "cba"
نصوص.تكبير(س)	تحويل لكبيرة	نصوص.تكبير("abc") → "ABC"
نصوص.تصغير(س)	تحويل لصغيرة	نصوص.تصغير("ABC") → "abc"
نصوص.تنسيق(...)	تنسيق النص	نصوص.تنسيق("%d", 42)

📋 مكتبة الجداول (جدول)

الدالة	الوصف	مثال
جدول.إدراج(ج,ق)	إضافة عنصر	جدول.إدراج(قائمة, 5)
جدول.حذف(ج,م)	حذف عنصر	جدول.حذف(قائمة, 1)
جدول.ترتيب(ج)	ترتيب الجدول	جدول.ترتيب(قائمة)
جدول.دمج(ج,ف)	دمج كنص	جدول.دمج(قائمة, ",")

🖥️ مكتبة النظام (نظام)

الدالة	الوصف	مثال
نظام.وقت()	الوقت الحالي	نظام.وقت()
نظام.تاريخ(ف)	التاريخ المنسق	نظام.تاريخ("%Y-%m-%d")
نظام.خرج(ك)	إنهاء البرنامج	نظام.خرج(0)
نظام.تنفيذ(أ)	تنفيذ أمر	نظام.تنفيذ("dir")

📁 مكتبة الإدخال/الإخراج (دخل_خرج)

الدالة	الوصف
دخل_خرج.فتح(ملف,نمط)	فتح ملف
دخل_خرج.قراءة()	قراءة من المدخلات
دخل_خرج.كتابة(...)	كتابة للمخرجات

---

🔤 جدول الكلمات المفتاحية

الكلمات المفتاحية الأساسية

العربية	الإنجليزية	الوصف
محلي	local	تعريف متغير محلي
دالة	function	تعريف دالة
نهاية	end	إنهاء كتلة
ارجع	return	إرجاع قيمة
إذا	if	شرط
إذن	then	بداية كتلة الشرط
وإلا	else	الحالة البديلة
وإلا_إذا	elseif	شرط بديل
لكل	for	حلقة تكرار
طالما	while	حلقة شرطية
افعل	do	بداية كتلة الحلقة
كرر	repeat	حلقة كرر
حتى	until	شرط إنهاء الكرر
اكسر	break	كسر الحلقة
في	in	في (للتكرار)

القيم المنطقية

العربية	الإنجليزية	الوصف
صح	true	صحيح
خطأ	false	خاطئ
لاشيء	nil	قيمة فارغة

العمليات المنطقية

العربية	الإنجليزية	الوصف
و	and	و المنطقية
أو	or	أو المنطقية
ليس	not	النفي

الدوال الأساسية

العربية	الإنجليزية	الوصف
اطبع	print	طباعة على الشاشة
نوع	type	نوع المتغير
تحويل_لرقم	tonumber	تحويل لرقم
تحويل_لنص	tostring	تحويل لنص
أزواج	pairs	تكرار على جدول
أزواج_رقمية	ipairs	تكرار رقمي

---

📊 مقارنة مع اللغات الأخرى

ياقوت vs Python

الميزة	ياقوت	Python
سهولة التعلم	⭐⭐⭐⭐⭐	⭐⭐⭐⭐⭐
الكلمات المفتاحية العربية	✅	❌
المكتبات المعربة	✅	❌
الأداء	⭐⭐⭐⭐	⭐⭐⭐
حجم الملف التنفيذي	~200KB	~30MB
التضمين في الألعاب	✅	🟡
المجتمع	🟡	⭐⭐⭐⭐⭐

ياقوت vs JavaScript

الميزة	ياقوت	JavaScript
سهولة التعلم	⭐⭐⭐⭐⭐	⭐⭐⭐
الكلمات المفتاحية العربية	✅	❌
التوافق مع الويب	❌	✅
الأداء	⭐⭐⭐⭐	⭐⭐⭐⭐
التعقيد	منخفض	متوسط

ياقوت vs Lua

الميزة	ياقوت	Lua
نفس المحرك	✅	✅
الكلمات العربية	✅	❌
المكتبات المعربة	✅	❌
التوافق	100%	-
المجتمع	🟡	⭐⭐⭐⭐

---

❓ الأسئلة الشائعة

س1: هل ياقوت مجانية؟

ج: نعم، ياقوت مفتوحة المصدر ومجانية تماماً تحت رخصة MIT.

س2: هل يمكنني استخدام ياقوت في مشاريع تجارية؟

ج: نعم، رخصة MIT تسمح بالاستخدام التجاري.

س3: هل ياقوت متوافقة مع كود Lua العادي؟

ج: نعم، ياقوت متوافقة 100% مع Lua. يمكنك تشغيل أي كود Lua.

س4: كيف أتعلم ياقوت؟

ج: ابدأ بقراءة:

1. DOCS_AR.md - التوثيق الأساسي
2. YAQOUT_BOOK.md - كتاب تعليمي شامل
3. مجلد testes/ - أمثلة وتجارب

س5: لماذا لا تظهر الحروف العربية بشكل صحيح؟

ج: تأكد من:

• حفظ الملف بترميز UTF-8
• استخدام طرفية تدعم UTF-8
• في Windows CMD: chcp 65001

س6: هل يمكنني المساهمة في المشروع؟

ج: بالتأكيد! راجع ملف CONTRIBUTING.md للتفاصيل.

س7: أين يمكنني الإبلاغ عن مشكلة؟

ج: افتح Issue جديد على GitHub مع وصف تفصيلي للمشكلة.

س8: هل ياقوت تعمل على Linux/Mac؟

ج: نعم، يمكن تجميعها على أي نظام يدعم GCC.

---

🤝 المساهمة

نرحب بجميع المساهمات! يمكنك المساهمة في:

• 🌐 تعريب المزيد من المكتبات
• 📖 كتابة التوثيق والأمثلة
• 🐛 الإبلاغ عن الأخطاء وإصلاحها
• ⭐ نشر المشروع ودعمه

راجع CONTRIBUTING.md للتفاصيل الكاملة.

---

👨‍💻 المطور

• المطور الرئيسي: إسلام النشار (Islam Al-Nashar)
• المؤسسة: ستوديو النشار (Al-Nashar Studio)
• السنة: 2026

---

📜 الترخيص

هذا المشروع مفتوح المصدر ومتاح تحت رخصة MIT.

MIT License

Copyright (c) 2026 Islam Al-Nashar (Al-Nashar Studio)

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software.

---

🏷️ الوسوم (Tags)

arabic-programming-language lua-arabic yaqout-lang arabic-coding programming-in-arabic language-localization scripting-language compilers open-source education

---

---

💎 Yaqout Language (English)

A Full Arabic Programming Language Based on Lua 5.5

Yaqout is a powerful and fast scripting language, developed as a full Arabic version of Lua. It aims to empower Arabic developers to write code in their native language while maintaining high performance.

Main Features

• Full Arabic Keywords: (إذا, إذن, دالة, محلي...)
• Unicode Support: Native Arabic variable and function names
• Localized Standard Libraries: Math, String, Table, and OS libraries in Arabic
• Custom Extensions: Supports .yaqout and .yq files
• VS Code Support: Syntax highlighting and custom icons
• 100% Lua Compatible: Run any Lua code

Quick Start

محلي الاسم = "World"
اطبع("مرحباً " .. الاسم)

Installation

# Download yaqout.exe and run:
yaqout.exe your_script.yq

Documentation

• DOCS_AR.md - Arabic documentation
• YAQOUT_BOOK.md - Comprehensive learning book
• CONTRIBUTING.md - Contribution guide

Developer

• Lead Developer: Islam Al-Nashar
• Organization: Al-Nashar Studio

License

MIT License - Free for personal and commercial use.

---

معاً نبني مستقبل البرمجة العربية! 🚀