# Solan — full bilingual reference Canonical website: https://solovip.me Source repository: https://github.com/kingxsolo/Solan Source snapshot: 8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad Documentation index: https://solovip.me/docs Install page (separate, not duplicated): https://solovip.me/install > Content is derived from the linked repository and the public site. Source-derived examples are not claims of successful execution unless explicitly stated. # دليل التعلّم الحالي — العربية ## ما هي سولان؟ **البداية** سولان لغة برمجة عربية: كلماتها المفتاحية ودوالها ومكتباتها كلها بالعربية. تعمل بمفسّر بايتكود مكتوب بلغة C مع مترجم JIT، وتأتي كملف تنفيذي واحد فيه مكتبة قياسية واسعة (ويب، قواعد بيانات، JSON، تعابير نمطية، ضغط…). - ملفات الكود تنتهي بـ `.سو` أو `.sn`. - النص يُكتب من اليمين إلى اليسار، ويمكنك استخدام الأرقام العربية (٣ + ٤). - التعليقات: `//` لسطر، و`/* ... */` لعدة أسطر. - الفاصلة العربية «،» تُقبل في المعاملات والقوائم، كما تُقبل الفاصلة العادية. ## أول برنامج **البداية** أنشئ ملفاً اسمه `هلا.سو`: **هلا.سو** ```solan اطبع("هلا يا عالم") خل اسم = "سولان" اطبع("مرحبا ${اسم}، ٢+٣ = ${2+3}") ``` Output: ```text هلا يا عالم مرحبا سولان، ٢+٣ = 5 ``` ثم شغّله من الطرفية: **terminal** ```text solan هلا.سو ``` | الأمر | وظيفته | | --- | --- | | `solan ملف.سو` | تشغيل ملف | | `solan` | الوضع التفاعلي (جرّب الأوامر سطراً بسطر) | | `solan -e "اطبع(1+1)"` | تشغيل كود مباشرة من الطرفية | | `solan -v` | عرض الإصدار | ## المتغيرات والأنواع **أساسيات اللغة** `خل` تعرّف متغيراً يمكن تغييره، و`ثابت` تعرّف قيمة لا تتغير. الدالة `نوع()` تخبرك بنوع أي قيمة. **أنواع.سو** ```solan خل اسم = "سولان" خل عمر = 3 ثابت باي = 3.14159 خل فعال = صح خل لا_شيء = عدم اطبع(نوع(اسم), نوع(عمر), نوع(فعال), نوع([1]), نوع({"أ": 1})) اطبع("بعد سنتين عمرك ${عمر + 2}") ``` Output: ```text نص رقم منطقي قائمة قاموس بعد سنتين عمرك 5 ``` | النوع | مثال | ملاحظة | | --- | --- | --- | | نص | `"مرحبا"` | بين علامتي اقتباس، ويدعم `${تعبير}` داخله | | رقم | `42` و`3.14` | كل الأرقام عشرية مزدوجة | | منطقي | `صح` / `غلط` | | | قائمة | `[1, 2, 3]` | | | قاموس | `{"اسم": "ليلى"}` | مفاتيح نصية | | عدم | `عدم` | تعني «لا قيمة» | > لا يوجد تحويل ضمني بين النص والرقم. استعمل `${}` أو `نص()` أو `رقم()`: `رقم("42") + 1` تعطي 43. ## العمليات **أساسيات اللغة** **عمليات.سو** ```solan اطبع(10 / 4, 10 % 3, 2 ** 10) خل أ = 7 اطبع(أ > 5 و أ < 10) // و اطبع(أ == 3 او أ == 7) // او اطبع(ليس (أ == 7)) // ليس خل اسم = عدم اطبع(اسم ?? "زائر") // قيمة افتراضية إن كان عدم ``` Output: ```text 2.5 1 1024 صح صح غلط زائر ``` للوصول الآمن لخاصية قد لا توجد استعمل `?.`: التعبير `ن?.ا` يعطي `عدم` بدل الخطأ إن كان `ن` فارغاً. ## الشروط **أساسيات اللغة** **شروط.سو** ```solan خل درجة = 85 اذا درجة >= 90 { اطبع("ممتاز") } والا_اذا درجة >= 70 { اطبع("جيد") } والا { اطبع("حاول مرة أخرى") } ``` Output: ```text جيد ``` لا حاجة لأقواس حول الشرط. وللاختيار بين قيم كثيرة استعمل `تبديل`، ويمكن لـ`حالة` أن تأخذ عدة قيم مفصولة بفاصلة: **تبديل.سو** ```solan دالة وصف(ن) { تبديل ن { حالة 1، 2 { ارجع "صغير" } حالة 3 { ارجع "ثلاثة" } افتراضي { ارجع "غير معروف" } } } اطبع(وصف(1), وصف(3), وصف(9)) ``` Output: ```text صغير ثلاثة غير معروف ``` ## الحلقات **أساسيات اللغة** **حلقات.سو** ```solan // من 0 إلى 2 لكل س في مدى(3) { اطبع("س =", س) } // من 0 إلى 10 بخطوة 5 لكل س في مدى(0, 10, 5) { اطبع(س) } // طالما الشرط صحيح خل ع = 0 طالما ع < 3 { ع += 1 } // تكرار عدد من المرات كرر 2 { اطبع("تكرار") } // استمر تتخطى العنصر، وتوقف تنهي الحلقة لكل ي في [1, 2, 3, 4, 5] { اذا ي == 2 { استمر } اذا ي == 4 { توقف } اطبع(ي) } ``` Output: ```text س = 0 س = 1 س = 2 0 5 تكرار تكرار 1 3 ``` `مدى` كسولة: `مدى(0, 30000000)` داخل `لكل` لا تبني قائمة في الذاكرة. وللمرور على قاموس بمفتاحه وقيمته معاً: ```solan لكل ك، ق في {"أ": 1, "ب": 2} { اطبع(ك, ق) } ``` Output: ```text أ 1 ب 2 ``` ## الدوال **أساسيات اللغة** **دوال.سو** ```solan دالة تحية(اسم, لغة = "ع") { ارجع "أهلا " + اسم } اطبع(تحية("سامي")) // دالة سهمية خل مربع = س => س * س اطبع(مربع(5)) // عدد مفتوح من المعاملات دالة جمع(...ارقام) { ارجع ارقام.اطوي((م, س) => م + س, 0) } اطبع(جمع(1, 2, 3, 4)) ``` Output: ```text أهلا سامي 25 10 ``` - القيمة الافتراضية للمعامل: `لغة = "ع"`. - `...ارقام` تجمع بقية المعاملات في قائمة، و`...قائمة` عند الاستدعاء تفرد القائمة. - الدوال قيم عادية: تُخزَّن في متغيرات وتُمرَّر لدوال أخرى. > أسماء مثل `و` و`او` و`نفي` و`عدم` و`نهاية` محجوزة ولا تصلح أسماء معاملات. ## القوائم والقواميس **البيانات** **قوائم.سو** ```solan خل ق = [5, 3, 8] ق.اضف(1) اطبع(ق.طول, ق[0], ق[-1]) اطبع([1, 2, 3, 4, 5, 6].رشح(ي => ي % 2 == 0).حول(ي => ي * ي).مجموع()) خل مرتبة = [5, 3, 8, 1] مرتبة.رتب() اطبع(مرتبة, مرتبة.يحتوي(3), مرتبة.ابحث(8)) ``` Output: ```text 4 5 1 56 [1، 3، 5، 8] صح 3 ``` | الدالة | عملها | | --- | --- | | `اضف(ع)` | إضافة عنصر في النهاية | | `رشح(د)` | عناصر تحقق الشرط | | `حول(د)` | تحويل كل عنصر | | `اطوي(د, بداية)` | اختزال القائمة لقيمة واحدة | | `رتب()` `اعكس()` | الترتيب والعكس (يعدّلان القائمة نفسها) | | `جزء(من, الى)` `يحتوي(ع)` `ابحث(ع)` | اقتطاع، فحص وجود، موضع العنصر | | `مجموع()` `طول` | مجموع الأرقام، وعدد العناصر | القواميس: المفتاح الناقص يرمي خطأ، فاستعمل `.احصل(مفتاح, افتراضي)` أو الكلمة `في` للفحص. **قواميس.سو** ```solan خل شخص = {"اسم": "ليلى", "عمر": 25} شخص["بلد"] = "مصر" اطبع(شخص.اسم, شخص.مفاتيح()) اطبع(شخص.احصل("هاتف", "غير مسجل"), "اسم" في شخص) ``` Output: ```text ليلى ["اسم"، "عمر"، "بلد"] غير مسجل صح ``` التفكيك وتبديل القيم: ```solan خل [ص, ع] = [1, 2] [ص, ع] = [ع, ص] اطبع(ص, ع) خل ك = [1, 2] خل كبيرة = [0, ...ك, 3] // نشر القائمة ``` Output: ```text 2 1 ``` ## النصوص **البيانات** **نصوص.سو** ```solan خل س = "مرحبا" اطبع(س.قسم("ر"), س.يحتوي("رح"), س.ابدل("م", "ك")) اطبع("اب".كرر(3), "سولان".يبدأ_ب("سو"), " نص ".نظف()) اطبع(نسق("{:.2f} ثانية", 1.23456)) ``` Output: ```text ["م"، "حبا"] صح كرحبا اباباب صح نص 1.23 ثانية ``` > دمج النصوص بـ `+` داخل حلقة طويلة بطيء (يعيد النسخ كل مرة). لبناء نص كبير استعمل `نصوص.بناء()` فهو خطي. ## الأصناف والوراثة **البرمجة الكائنية** **اصناف.سو** ```solan صنف حيوان { بناء(اسم) { هذا.اسم = اسم } صوت() { ارجع "..." } عرف() { اطبع(هذا.اسم + " يقول " + هذا.صوت()) } } صنف قط يرث حيوان { صوت() { ارجع "مياو" } } قط("ميمي").عرف() ``` Output: ```text ميمي يقول مياو ``` - `بناء` هو المُنشئ، و`هذا` هو الكائن الحالي. - `يرث` للوراثة، و`الاب` للوصول إلى الصنف الأب. - إنشاء كائن: استدعِ اسم الصنف كدالة: `قط("ميمي")`. ## الأخطاء **البرمجة الكائنية** **اخطاء.سو** ```solan حاول { ارمي "حدث خطأ" } امسك (خ) { اطبع("أمسكت:", خ) } اخيرا { اطبع("انتهى") } حاول { خل ز = 1 / 0 } امسك (خ) { اطبع(خ) } ``` Output: ```text أمسكت: حدث خطأ انتهى القسمة على صفر (سطر 9) ``` رسائل الخطأ في سولان بالعربية وتعرض السطر ومقتطفاً من الكود، وتقترح الاسم الصحيح إن أخطأت في كتابة دالة. ## التعداد والأنواع الاختيارية **البرمجة الكائنية** **تعداد.سو** ```solan تعداد اللون { احمر، اخضر = 5، ازرق } اطبع(اللون.احمر, اللون.اخضر, اللون.ازرق) ``` Output: ```text 0 5 6 ``` الأنواع اختيارية: تكتبها حين تريد حماية أكبر. الفحص يتم وقت التشغيل عند التعريف والإسناد ودخول الدالة والإرجاع. **انواع.سو** ```solan خل س: رقم = 5 دالة ضعف(أ: رقم): رقم { ارجع أ * 2 } اطبع(ضعف(س)) خل ص: رقم = "نص" // خطأ ``` Output: ```text 10 خطأ: خطأ في النوع: المتغير 'ص' يتوقع 'رقم' لكن وجدت 'نص' (سطر 5) ``` الأنواع المعروفة: `رقم`، `عدد_صحيح`، `نص`، `منطقي`، `قائمة`، `قاموس`، `دالة`، `عدم`، `اي`، وأسماء الأصناف. ويمكن الجمع بـ `رقم | نص` وللاختياري `نص?`. ## البرمجة غير المتزامنة **متقدم** **غير_متزامن.سو** ```solan غير_متزامن دالة مهمة(اسم, ثواني) { انتظر نم(ثواني) ارجع "انتهت ${اسم}" } غير_متزامن دالة رئيسي() { خل نتائج = انتظر كل_الوعود([مهمة("أ", 0.1), مهمة("ب", 0.1)]) اطبع(نتائج) } شغل(رئيسي) ``` Output: ```text ["انتهت أ"، "انتهت ب"] ``` لتوزيع عمل ثقيل على أنوية المعالج استعمل مكتبة `عمال` (عمليات فرعية معزولة)، وفي الأعمال الخفيفة `انتظر عملية(دالة)`. ## الاستيراد والمكتبة القياسية **المكتبات** **مكتبات.سو** ```solan استورد "جيسون" استورد "رياضيات" استورد "ملفات" خل بيانات = {"اسم": "سامي", "نقاط": [1, 2, 3]} خل نص_ج = جيسون.ترميز(بيانات) اطبع(نص_ج) اطبع(جيسون.فك(نص_ج).نقاط) اطبع(رياضيات.جذر(144), رياضيات.اكبر(3, 9)) ملفات.اكتب("مرحبا.txt", "سطر أول") اطبع(ملفات.اقرا("مرحبا.txt"), ملفات.موجود("مرحبا.txt")) ``` Output: ```text {"اسم":"سامي","نقاط":[1,2,3]} [1، 2، 3] 12 9 سطر أول صح ``` المكتبات المدمجة في الملف التنفيذي، وتُستورد بالاسم: | المكتبة | الوظيفة | | --- | --- | | `شبكة` `ويبسوكت` `سوكت` | HTTP وخوادم وWebSocket وTCP (مع TLS) | | `قاعدة` | قواعد بيانات SQLite | | `جيسون` `نمط` `ضغط` | JSON، تعابير نمطية، gzip/zlib | | `ملفات` `مسارات` `نظام` | الملفات والمسارات وبيئة النظام | | `رياضيات` `عشوائي` `ضخم` `زمن` `تواريخ` | الحساب والأعداد الكبيرة والوقت والتاريخ الهجري | | `نصوص` `جداول` `ألوان` `عرض` | معالجة النصوص وCSV وألوان الطرفية وتنسيق الأرقام | | `سجل` `اختبار` `وسائط` `عمال` | السجلات، الاختبارات، خيارات سطر الأوامر، العمليات المتوازية | | `مجموعات` `ذاكرة` `مخطط` `قوالب` `نتيجة` `بث` | هياكل بيانات، ذاكرة مؤقتة، تحقق من البيانات، قوالب، نتيجة/خيار، أحداث | ## المرادفات **المكتبات** لكل كلمة في سولان مرادفات تعمل بنفس المعنى، فتكتب بالكلمة التي تعوّدت عليها. ولا فرق في الهمزات (أ/إ/ا) ولا ة/ه ولا التشكيل. **مرادفات.سو** ```solan متغير س = 5 وظيفة ضعف(ن) { ارجع ن * 2 } لو س > 3 { اعرض(ضعف(س)) } ``` Output: ```text 10 ``` | المعنى | القياسي | مرادفات | | --- | --- | --- | | متغير | `خل` | `متغير` `ليكن` `اجعل` | | دالة | `دالة` | `وظيفة` `اجراء` | | شرط | `اذا` | `إذا` `لو` `في_حال` | | حلقة | `لكل` | `لاجل` `من_اجل` | | إرجاع | `ارجع` | `اعد` `رجع` | | طباعة | `اطبع` | `اعرض` `اظهر` | لتوحيد كود فيه مرادفات مختلفة إلى الكلمات القياسية: **terminal** ```text solan fmt ملف.سو --قياسي -w ``` ## أدوات سطر الأوامر **الأدوات** | الأمر | وظيفته | | --- | --- | | `solan ملف.سو` | تشغيل ملف | | `solan --check ملف.سو` | فحص الصياغة بدون تشغيل | | `solan fmt ملف.سو -w` | تنسيق الكود وكتابته في الملف | | `solan --لون ملف.سو` | عرض الكود ملوناً (و`--html` لتصديره) | | `solan --تتبع ملف.سو` | طباعة كل سطر ينفَّذ | | `solan --تصحيح ملف.سو` | مصحّح تفاعلي خطوة بخطوة | | `solan lsp` | خادم اللغة للمحررات (إكمال وأخطاء) | | `make doctor` | فحص بيئتك قبل التثبيت | إضافة VS Code للتلوين والإكمال موجودة في مجلد `editor/vscode` داخل ريبو اللغة. ## الصلاحيات **الأدوات** يمكنك تشغيل سكربت لا تثق به وتحدد له بالضبط ما يستطيع فعله. الفئات: `قراءة` `كتابة` `شبكة` `تنفيذ` `بيئة` `اصلي`. **terminal** ```text solan --اسمح-قراءة=/بيانات --اسمح-كتابة=/مخرجات سكربت.سو solan --اسمح-شبكة=api.example.com سكربت.سو solan --امنع=تنفيذ,شبكة سكربت.سو ``` ## الحزم والمكاتب من جيتهاب **الأدوات** لا يوجد مخزن مركزي: أي مستودع على جيتهاب يصلح مكتبة. تُحفظ مرة واحدة في مجلد المستخدم وتُشارَك بين مشاريعك، ويحتوي مشروعك على `solan.json` (ما تريد) و`solan.lock` (ما حصلت عليه بالضبط). **terminal** ```text solan init # ينشئ solan.json solan add صاحب/مستودع # يضيف مكتبة من جيتهاب solan add صاحب/مستودع@^1.2.0 # بنطاق إصدارات solan install # يثبّت ما في solan.json solan install --frozen # حسب القفل فقط (للتكامل المستمر) solan verify # يتحقق من بصمات المكتبات ``` الإصدارات هي وسوم git بشكل `vX.Y.Z`. ثم تستوردها باسمها: **solan.json** ```solan { "الاسم": "بوتي", "النسخة": "0.1.0", "الاعتماديات": { "ادوات": "صاحب/مستودع@^1.2.0" } } ``` > تريد نشر مكتبتك؟ ارفعها على جيتهاب بوسم إصدار، ثم أضفها في صفحة المكاتب هنا. # Current learning guide — English ## What is Solan? **Getting started** Solan is a programming language written in Arabic: its keywords, functions and libraries are all Arabic. It runs on a bytecode interpreter written in C with a JIT compiler, and ships as a single executable with a broad standard library (web, databases, JSON, regular expressions, compression…). - Source files end in `.سو` or `.sn`. - Text is written right to left, and Arabic digits work too (٣ + ٤). - Comments: `//` for one line and `/* ... */` for several. - The Arabic comma «،» is accepted in arguments and lists, alongside the regular comma. ## Your first program **Getting started** Create a file named `هلا.سو`: **هلا.سو** ```solan اطبع("هلا يا عالم") خل اسم = "سولان" اطبع("مرحبا ${اسم}، ٢+٣ = ${2+3}") ``` Output: ```text هلا يا عالم مرحبا سولان، ٢+٣ = 5 ``` Then run it from the terminal: **terminal** ```text solan هلا.سو ``` | Command | What it does | | --- | --- | | `solan ملف.سو` | Run a file | | `solan` | Interactive mode (try commands line by line) | | `solan -e "اطبع(1+1)"` | Run code straight from the terminal | | `solan -v` | Show the version | ## Variables and types **Language basics** `خل` declares a variable you can change; `ثابت` declares a value that never changes. The `نوع()` function tells you the type of any value. **أنواع.سو** ```solan خل اسم = "سولان" خل عمر = 3 ثابت باي = 3.14159 خل فعال = صح خل لا_شيء = عدم اطبع(نوع(اسم), نوع(عمر), نوع(فعال), نوع([1]), نوع({"أ": 1})) اطبع("بعد سنتين عمرك ${عمر + 2}") ``` Output: ```text نص رقم منطقي قائمة قاموس بعد سنتين عمرك 5 ``` | Type | Example | Note | | --- | --- | --- | | text | `"مرحبا"` | Between quotes, and supports `${expression}` inside | | number | `42` and `3.14` | All numbers are double-precision floats | | boolean | `صح` / `غلط` | true / false | | list | `[1, 2, 3]` | | | dictionary | `{"اسم": "ليلى"}` | Text keys | | nothing | `عدم` | Means “no value” | > There is no implicit conversion between text and numbers. Use `${}`, `نص()` or `رقم()`: `رقم("42") + 1` gives 43. ## Operators **Language basics** **عمليات.سو** ```solan اطبع(10 / 4, 10 % 3, 2 ** 10) خل أ = 7 اطبع(أ > 5 و أ < 10) // و اطبع(أ == 3 او أ == 7) // او اطبع(ليس (أ == 7)) // ليس خل اسم = عدم اطبع(اسم ?? "زائر") // قيمة افتراضية إن كان عدم ``` Output: ```text 2.5 1 1024 صح صح غلط زائر ``` For safe access to a property that may not exist use `?.`: the expression `ن?.ا` gives `عدم` instead of an error when `ن` is empty. ## Conditions **Language basics** **شروط.سو** ```solan خل درجة = 85 اذا درجة >= 90 { اطبع("ممتاز") } والا_اذا درجة >= 70 { اطبع("جيد") } والا { اطبع("حاول مرة أخرى") } ``` Output: ```text جيد ``` No parentheses are needed around the condition. To choose between many values use `تبديل`; a `حالة` can take several values separated by commas: **تبديل.سو** ```solan دالة وصف(ن) { تبديل ن { حالة 1، 2 { ارجع "صغير" } حالة 3 { ارجع "ثلاثة" } افتراضي { ارجع "غير معروف" } } } اطبع(وصف(1), وصف(3), وصف(9)) ``` Output: ```text صغير ثلاثة غير معروف ``` ## Loops **Language basics** **حلقات.سو** ```solan // من 0 إلى 2 لكل س في مدى(3) { اطبع("س =", س) } // من 0 إلى 10 بخطوة 5 لكل س في مدى(0, 10, 5) { اطبع(س) } // طالما الشرط صحيح خل ع = 0 طالما ع < 3 { ع += 1 } // تكرار عدد من المرات كرر 2 { اطبع("تكرار") } // استمر تتخطى العنصر، وتوقف تنهي الحلقة لكل ي في [1, 2, 3, 4, 5] { اذا ي == 2 { استمر } اذا ي == 4 { توقف } اطبع(ي) } ``` Output: ```text س = 0 س = 1 س = 2 0 5 تكرار تكرار 1 3 ``` `مدى` is lazy: `مدى(0, 30000000)` inside `لكل` doesn’t build a list in memory. To walk a dictionary with its key and value together: ```solan لكل ك، ق في {"أ": 1, "ب": 2} { اطبع(ك, ق) } ``` Output: ```text أ 1 ب 2 ``` ## Functions **Language basics** **دوال.سو** ```solan دالة تحية(اسم, لغة = "ع") { ارجع "أهلا " + اسم } اطبع(تحية("سامي")) // دالة سهمية خل مربع = س => س * س اطبع(مربع(5)) // عدد مفتوح من المعاملات دالة جمع(...ارقام) { ارجع ارقام.اطوي((م, س) => م + س, 0) } اطبع(جمع(1, 2, 3, 4)) ``` Output: ```text أهلا سامي 25 10 ``` - Default parameter value: `لغة = "ع"`. - `...ارقام` gathers the remaining arguments into a list, and `...قائمة` at a call site spreads a list out. - Functions are ordinary values: store them in variables and pass them to other functions. > Names such as `و`, `او`, `نفي`, `عدم` and `نهاية` are reserved and can’t be parameter names. ## Lists and dictionaries **Data** **قوائم.سو** ```solan خل ق = [5, 3, 8] ق.اضف(1) اطبع(ق.طول, ق[0], ق[-1]) اطبع([1, 2, 3, 4, 5, 6].رشح(ي => ي % 2 == 0).حول(ي => ي * ي).مجموع()) خل مرتبة = [5, 3, 8, 1] مرتبة.رتب() اطبع(مرتبة, مرتبة.يحتوي(3), مرتبة.ابحث(8)) ``` Output: ```text 4 5 1 56 [1، 3، 5، 8] صح 3 ``` | Function | What it does | | --- | --- | | `اضف(ع)` | Append an item | | `رشح(د)` | Items that pass the test | | `حول(د)` | Transform every item | | `اطوي(د, بداية)` | Reduce the list to one value | | `رتب()` `اعكس()` | Sort and reverse (they modify the list itself) | | `جزء(من, الى)` `يحتوي(ع)` `ابحث(ع)` | Slice, membership test, index of an item | | `مجموع()` `طول` | Sum of numbers, and number of items | Dictionaries: a missing key raises an error, so use `.احصل(key, default)` or the word `في` to test. **قواميس.سو** ```solan خل شخص = {"اسم": "ليلى", "عمر": 25} شخص["بلد"] = "مصر" اطبع(شخص.اسم, شخص.مفاتيح()) اطبع(شخص.احصل("هاتف", "غير مسجل"), "اسم" في شخص) ``` Output: ```text ليلى ["اسم"، "عمر"، "بلد"] غير مسجل صح ``` Destructuring and swapping values: ```solan خل [ص, ع] = [1, 2] [ص, ع] = [ع, ص] اطبع(ص, ع) خل ك = [1, 2] خل كبيرة = [0, ...ك, 3] // نشر القائمة ``` Output: ```text 2 1 ``` ## Text **Data** **نصوص.سو** ```solan خل س = "مرحبا" اطبع(س.قسم("ر"), س.يحتوي("رح"), س.ابدل("م", "ك")) اطبع("اب".كرر(3), "سولان".يبدأ_ب("سو"), " نص ".نظف()) اطبع(نسق("{:.2f} ثانية", 1.23456)) ``` Output: ```text ["م"، "حبا"] صح كرحبا اباباب صح نص 1.23 ثانية ``` > Joining text with `+` inside a long loop is slow (it copies each time). To build a large string use `نصوص.بناء()`, which is linear. ## Classes and inheritance **Object-oriented** **اصناف.سو** ```solan صنف حيوان { بناء(اسم) { هذا.اسم = اسم } صوت() { ارجع "..." } عرف() { اطبع(هذا.اسم + " يقول " + هذا.صوت()) } } صنف قط يرث حيوان { صوت() { ارجع "مياو" } } قط("ميمي").عرف() ``` Output: ```text ميمي يقول مياو ``` - `بناء` is the constructor and `هذا` is the current object. - `يرث` is inheritance, and `الاب` reaches the parent class. - Create an object by calling the class like a function: `قط("ميمي")`. ## Errors **Object-oriented** **اخطاء.سو** ```solan حاول { ارمي "حدث خطأ" } امسك (خ) { اطبع("أمسكت:", خ) } اخيرا { اطبع("انتهى") } حاول { خل ز = 1 / 0 } امسك (خ) { اطبع(خ) } ``` Output: ```text أمسكت: حدث خطأ انتهى القسمة على صفر (سطر 9) ``` Error messages in Solan are in Arabic, show the line with a code excerpt, and suggest the right name if you mistype a function. ## Enums and optional types **Object-oriented** **تعداد.سو** ```solan تعداد اللون { احمر، اخضر = 5، ازرق } اطبع(اللون.احمر, اللون.اخضر, اللون.ازرق) ``` Output: ```text 0 5 6 ``` Types are optional: add them when you want extra safety. Checks happen at runtime on declaration, assignment, function entry and return. **انواع.سو** ```solan خل س: رقم = 5 دالة ضعف(أ: رقم): رقم { ارجع أ * 2 } اطبع(ضعف(س)) خل ص: رقم = "نص" // خطأ ``` Output: ```text 10 خطأ: خطأ في النوع: المتغير 'ص' يتوقع 'رقم' لكن وجدت 'نص' (سطر 5) ``` Known types: `رقم`, `عدد_صحيح`, `نص`, `منطقي`, `قائمة`, `قاموس`, `دالة`, `عدم`, `اي`, and class names. Combine with `رقم | نص`, and mark optional with `نص?`. ## Asynchronous programming **Advanced** **غير_متزامن.سو** ```solan غير_متزامن دالة مهمة(اسم, ثواني) { انتظر نم(ثواني) ارجع "انتهت ${اسم}" } غير_متزامن دالة رئيسي() { خل نتائج = انتظر كل_الوعود([مهمة("أ", 0.1), مهمة("ب", 0.1)]) اطبع(نتائج) } شغل(رئيسي) ``` Output: ```text ["انتهت أ"، "انتهت ب"] ``` To spread heavy work across CPU cores use the `عمال` library (isolated subprocesses); for light work, `انتظر عملية(function)`. ## Imports and the standard library **Libraries** **مكتبات.سو** ```solan استورد "جيسون" استورد "رياضيات" استورد "ملفات" خل بيانات = {"اسم": "سامي", "نقاط": [1, 2, 3]} خل نص_ج = جيسون.ترميز(بيانات) اطبع(نص_ج) اطبع(جيسون.فك(نص_ج).نقاط) اطبع(رياضيات.جذر(144), رياضيات.اكبر(3, 9)) ملفات.اكتب("مرحبا.txt", "سطر أول") اطبع(ملفات.اقرا("مرحبا.txt"), ملفات.موجود("مرحبا.txt")) ``` Output: ```text {"اسم":"سامي","نقاط":[1,2,3]} [1، 2، 3] 12 9 سطر أول صح ``` These libraries are built into the executable and imported by name: | Library | Purpose | | --- | --- | | `شبكة` `ويبسوكت` `سوكت` | HTTP, servers, WebSocket and TCP (with TLS) | | `قاعدة` | SQLite databases | | `جيسون` `نمط` `ضغط` | JSON, regular expressions, gzip/zlib | | `ملفات` `مسارات` `نظام` | Files, paths and the system environment | | `رياضيات` `عشوائي` `ضخم` `زمن` `تواريخ` | Math, big numbers, time and the Hijri calendar | | `نصوص` `جداول` `ألوان` `عرض` | Text processing, CSV, terminal colors and number formatting | | `سجل` `اختبار` `وسائط` `عمال` | Logging, tests, command-line options, parallel workers | | `مجموعات` `ذاكرة` `مخطط` `قوالب` `نتيجة` `بث` | Data structures, caching, data validation, templates, result/option, events | ## Synonyms **Libraries** Every Solan keyword has synonyms that mean exactly the same, so you can write with the word you’re used to. Hamza forms (أ/إ/ا), ة/ه and diacritics don’t matter. **مرادفات.سو** ```solan متغير س = 5 وظيفة ضعف(ن) { ارجع ن * 2 } لو س > 3 { اعرض(ضعف(س)) } ``` Output: ```text 10 ``` | Meaning | Standard | Synonyms | | --- | --- | --- | | variable | `خل` | `متغير` `ليكن` `اجعل` | | function | `دالة` | `وظيفة` `اجراء` | | condition | `اذا` | `إذا` `لو` `في_حال` | | loop | `لكل` | `لاجل` `من_اجل` | | return | `ارجع` | `اعد` `رجع` | | print | `اطبع` | `اعرض` `اظهر` | To normalize code that mixes synonyms into the standard words: **terminal** ```text solan fmt ملف.سو --قياسي -w ``` ## Command-line tools **Tools** | Command | What it does | | --- | --- | | `solan ملف.سو` | Run a file | | `solan --check ملف.سو` | Check syntax without running | | `solan fmt ملف.سو -w` | Format the code and write it back | | `solan --لون ملف.سو` | Show code colorized (`--html` to export) | | `solan --تتبع ملف.سو` | Print every line as it executes | | `solan --تصحيح ملف.سو` | Interactive step-by-step debugger | | `solan lsp` | Language server for editors (completion and errors) | | `make doctor` | Check your environment before installing | The VS Code extension for highlighting and completion lives in the `editor/vscode` folder of the language repo. ## Permissions **Tools** You can run a script you don’t trust and decide exactly what it may do. Categories: `قراءة` (read), `كتابة` (write), `شبكة` (network), `تنفيذ` (execute), `بيئة` (environment), `اصلي` (native). **terminal** ```text solan --اسمح-قراءة=/بيانات --اسمح-كتابة=/مخرجات سكربت.سو solan --اسمح-شبكة=api.example.com سكربت.سو solan --امنع=تنفيذ,شبكة سكربت.سو ``` ## Packages and libraries from GitHub **Tools** There is no central registry: any GitHub repository can be a library. Libraries are stored once in the user’s folder and shared across your projects. Your project holds `solan.json` (what you want) and `solan.lock` (exactly what you got). **terminal** ```text solan init # ينشئ solan.json solan add صاحب/مستودع # يضيف مكتبة من جيتهاب solan add صاحب/مستودع@^1.2.0 # بنطاق إصدارات solan install # يثبّت ما في solan.json solan install --frozen # حسب القفل فقط (للتكامل المستمر) solan verify # يتحقق من بصمات المكتبات ``` Versions are git tags in the form `vX.Y.Z`. Then you import them by name: **solan.json** ```solan { "الاسم": "بوتي", "النسخة": "0.1.0", "الاعتماديات": { "ادوات": "صاحب/مستودع@^1.2.0" } } ``` > Want to publish your library? Push it to GitHub with a version tag, then add it on the Libraries page here. # صياغة سولان والتحكم والتعبيرات — العربية ## الكلمات والمرادفات **الكتابة والرموز** يقرأ الماسح المعرّف أولًا ثم يطابق الكلمات المحجوزة؛ لذلك قد تكون للكلمة مجموعة مرادفات عربية. من أمثلة المجموعات المثبتة: `خل`/`متغير`/`ليكن`/`اجعل`، و`ثابت`/`دائم`، و`دالة`/`وظيفة`. | المفهوم | أسماء مثبتة في المصدر | | --- | --- | | تعريف قيمة متغيرة | `خل`، `متغير`، `ليكن`، `اجعل` | | تعريف قيمة ثابتة | `ثابت`، `دائم` | | تعريف دالة | `دالة`، `وظيفة` | | منطق | `صح`، `غلط`، `عدم` | | تدفق التحكم | `اذا`، `والا`، `طالما`، `لكل`، `كرر`، `ارجع`، `توقف`، `استمر` | > القائمة أمثلة لمجموعات الكلمات التي كشفها lexer/opcodes، وليست جدول ترجمة لكل اسم API في المكاتب. ## الأعداد والنصوص والاستيفاء **الكتابة والرموز** - يقبل الماسح أرقام ASCII والأرقام العربية، والبادئة `0x`، وشرطة سفلية داخل الرقم، والكسور والصيغة العلمية `e`/`E`. - تقبل النصوص الاقتباس المفرد أو المزدوج أو علامات «…». - الهروبات تشمل `\n` و`\t` و`\r` و`\0` والاقتباس والشرطة العكسية و`$`، إضافة إلى `\u` حتى أربع خانات سداسية و`\x` حتى خانتين. - يضمّن `${...}` تعبيرًا في النص. لا يوجد تحويل ضمني عند جمع نص مع نوع آخر؛ مصدر الـVM يقترح الاستيفاء أو `نص()` بحسب السياق. **مثال من README (لم يُعد تشغيله)** ```solan خل اسم = "عالم" اطبع("مرحبا يا ${اسم}") ``` > الحدود العددية وسلوك التحويل مذكورة كما ظهرت في الملفات المفحوصة؛ أمثلة الشيفرة هنا مصدرية ولم تُشغّل ضمن هذه المهمة. ## المعاملات والتعبيرات **التعبيرات والبيانات** المصدر يثبت معاملات حسابية `+ - * / % **`، ومقارنات `== != < <= > >=`، وقسمة صحيحة بالشرطة العكسية، ومعاملات بت `& | ^ << >>`. كلمات العضوية والمنطق تشمل `في`/`ضمن` و`و`/`أو`/`ليس`. - توجد الصيغ الشرطية `?:` و`??` والوصول الآمن `?.`. - `??` و`?.` يتعاملان مع `عدم`، و`&&` و`||` قصيرا الدارة. - لا نوثق هنا ترتيب أولوية للمعاملات؛ راجع الماسح والمحلل عند الحاجة إلى تفاصيل دقيقة. ## القوائم والقواميس والأنواع **التعبيرات والبيانات** - القوائم تكتب بين `[]` والقواميس بين `{}`، ويقبل المصدر الانتشار `...` في القوائم والقواميس ووسائط الاستدعاء. - توجد الفهرسة والشرائح `[بداية:نهاية]`؛ النهاية غير مشمولة. الفهرس السالب يحسب من نهاية النص أو القائمة ضمن الحدود. - القاموس يقبل الوصول إلى الخاصية، و`طول` مدعومة للنص والقائمة والقاموس. - تعريف المتغير والثابت يدعم قيد نوع بعد النقطتين والتفكيك؛ الثابت يحتاج قيمة ابتدائية. النوع `int` يتحقق من عدد صحيح ضمن حد المصدر. - الأنواع الموثقة في المحلل تشمل أنواعًا اختيارية واتحادًا باستخدام `|` وأسماء الأصناف. > الطرق متخصصة بنوع المستقبل؛ لا يعني ورود اسم طريقة في الملف أنها صالحة لكل نوع. راجع صفحة الطرق المدمجة. ## الدوال وبنى التحكم والاستثناءات **الدوال والتحكم** - المعاملات الافتراضية المتتابعة يجب أن تكون في نهاية التواقيع، ومعامل `...` المتبقي يأتي أخيرًا. - تدعم الدوال نوع إرجاع بعد المعاملات، وجسم تعبير بعد `=>`. - المحلل يدعم `if/else` و`while` و`for-in` و`repeat` و`switch` و`try/catch/finally` و`throw` والأصناف والوراثة. - الاستيراد مقصور على أعلى مستوى الملف في الملفات التي فُحصت. **مثال صياغي من ملفات المصدر — غير مشغّل** ```solan دالة جمع(أ: int, ب: int): int => أ + ب خل أرقام = [1, 2] اطبع(أرقام[-1]) ``` > الأمثلة تركيبية مستنتجة مباشرة من القواعد ولم تُشغّل على مفسّر Solan؛ استخدم `solan --check` بعد تثبيت اللغة للتحقق من أي مثال قبل الاعتماد عليه. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - src/compiler/lexer.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/lexer.inc - src/compiler/compiler.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/compiler.inc - src/vm/vm_core.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/vm_core.inc - src/vm/vm_run.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/vm_run.inc - src/vm/methods.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/methods.inc - src/compiler/opcodes.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/opcodes.inc # Solan Syntax, Control Flow, and Expressions — English ## Keywords and aliases **Lexicon and tokens** The lexer reads an identifier and then matches reserved words; a keyword can have several Arabic aliases. Confirmed groups include `خل`/`متغير`/`ليكن`/`اجعل`, `ثابت`/`دائم`, and `دالة`/`وظيفة`. | Concept | Source-confirmed spellings | | --- | --- | | Mutable binding | `خل`, `متغير`, `ليكن`, `اجعل` | | Constant binding | `ثابت`, `دائم` | | Function | `دالة`, `وظيفة` | | Literals | `صح`, `غلط`, `عدم` | | Control flow | `اذا`, `والا`, `طالما`, `لكل`, `كرر`, `ارجع`, `توقف`, `استمر` | > These are examples of lexer/opcode keyword groups, not translations of every library API. ## Numbers, strings, and interpolation **Lexicon and tokens** - The lexer accepts ASCII and Arabic-Indic digits, `0x` prefixes, underscores inside numbers, decimals, and `e`/`E` exponents. - Strings may use single quotes, double quotes, or «…». - Escapes include `\n`, `\t`, `\r`, `\0`, quotes, backslash and `$`, plus `\u` with up to four hex digits and `\x` with up to two. - `${...}` embeds an expression. Concatenating a string with another type does not implicitly convert it; the VM error points to interpolation or `نص()` as appropriate. **README example (not rerun)** ```solan خل اسم = "عالم" اطبع("مرحبا يا ${اسم}") ``` > Numeric boundaries and conversion behavior are summarized from the inspected source; code samples were not executed in this task. ## Operators and expressions **Expressions and data** The source confirms arithmetic `+ - * / % **`, comparisons `== != < <= > >=`, integer division with a backslash, and bitwise `& | ^ << >>`. Membership and logical words include `في`/`ضمن` and `و`/`أو`/`ليس`. - Conditional forms include `?:`, `??`, and safe access `?.`. - `??` and `?.` handle `عدم`; `&&` and `||` short-circuit. - Operator precedence is intentionally not asserted here; inspect the lexer/parser when exact precedence is required. ## Lists, maps, and types **Expressions and data** - Lists use `[]` and maps use `{}`; the source supports `...` spreading in lists, maps, and call arguments. - Indexing and slices `[start:end]` are available; the end is exclusive. Negative indexes count from the end for strings/lists when in range. - Map property access exists, and `طول` is supported for strings, lists, and maps. - Mutable and constant bindings support type annotations and destructuring; a constant requires an initializer. `int` checks for an integer within the source-defined limit. - The parser supports optional and union types (`|`) as well as class names. > Methods are receiver-type-specific; a name in the method file does not imply support on every type. See the built-in methods page. ## Functions, control flow, and exceptions **Functions and control flow** - Optional parameters must be trailing; a variadic `...` parameter comes last. - Functions support return annotations and expression bodies after `=>`. - The parser supports `if/else`, `while`, `for-in`, `repeat`, `switch`, `try/catch/finally`, `throw`, classes, and inheritance. - Imports are restricted to file top level in the inspected compiler files. **Source-derived syntax examples — not executed** ```solan دالة جمع(أ: int, ب: int): int => أ + ب خل أرقام = [1, 2] اطبع(أرقام[-1]) ``` > These examples are synthesized from parser rules and were not run with the Solan interpreter. After installation, verify examples with `solan --check` before relying on them. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - src/compiler/lexer.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/lexer.inc - src/compiler/compiler.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/compiler.inc - src/vm/vm_core.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/vm_core.inc - src/vm/vm_run.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/vm_run.inc - src/vm/methods.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/methods.inc - src/compiler/opcodes.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/opcodes.inc # الطرق المدمجة حسب نوع القيمة — العربية ## اختيار الطريقة تابع لنوع المستقبل **مبادئ** يسجل `src/vm/mids.inc` أسماء الطرق العربية، ثم يوجّه `builtin_method` التنفيذ حسب نوع المستقبل: نص أو قائمة أو قاموس. وجود الاسم في جدول mids لا يعني أنه يعمل على الأنواع الثلاثة؛ إذا لم يكن للنوع فرع تنفيذ تُرفض الطريقة. > الأعداد في عمود الوسائط هي حدود العدد التي يفرضها المصدر، وليست توثيقًا كاملًا لأنواع كل وسيط. الطرق المعرفة كخاصية مثل `طول` تستعمل بلا أقواس. ## طرق النصوص **النصوص** | الاسم | الوسائط | السلوك المثبت | | --- | --- | --- | | `طول` | خاصية | عدد المحارف UTF-8. | | `قسم(فاصل?)` | 0–1 | بلا فاصل يقسم على المسافة البيضاء ASCII؛ فاصل فارغ يقسم المحارف؛ وإلا يقسم على النص المحدد. | | `سطور()` | 0 | قائمة أسطر؛ يزيل CR قبل LF. | | `نظف()` | 0 | يحذف المسافات وtab وLF وCR من الطرفين. | | `كبير()` / `صغير()` | 0 | يحوّل ASCII a-z/A-Z فقط؛ لا يطبّق حالة Unicode على الحروف العربية. | | `يبدأ_ب(نص)` / `ينتهي_ب(نص)` | 1 | فحص بادئة أو لاحقة نصية. | | `يحتوي(نص)` | 1 | فحص وجود نص فرعي؛ النص الفارغ موجود. | | `ابدل(قديم، جديد)` | 2 | استبدال كل التطابقات غير المتداخلة؛ القديم الفارغ يعيد النص نفسه. | | `جزء(بداية، نهاية?)` | 1–2 | شريحة محارف بنهاية غير شاملة؛ الحدود تقص إلى المجال. | | `ابحث(نص)` | 1 | موضع التطابق بالمحارف، أو -1. | | `كرر(عدد)` | 1 | يكرر النص؛ العدد يجب أن يكون صحيحًا، والخرج محدود بـ512 MiB. | | `اعكس()` / `حروف()` | 0 | يعكس ترتيب المحارف أو يعيد قائمة محارف UTF-8. | | `نسق(...)` | بحسب المنسق | يفوض إلى منسق القيم في المصدر. | | `املأ_يسار(عرض، حشو?)` / `املأ_يمين(...)` | 1–2 | يضيف نص الحشو (افتراضيًا مسافة) حتى العرض المطلوب. | > المطابقة وحساب الطول في هذه الطرق يعتمدان على مواضع ومحارف UTF-8 كما يطبقها المصدر؛ `كبير` و`صغير` هنا تعديل ASCII فقط. ## طرق القوائم **القوائم** | الاسم | الوسائط | السلوك المثبت | | --- | --- | --- | | `طول` | خاصية | عدد العناصر. | | `اضف(...عناصر)` | 0 فأكثر | يضيف العناصر إلى القائمة نفسها ويعيدها. | | `ادرج(فهرس، قيمة)` | 2 | يدرج عند الفهرس؛ يقبل فهرسًا سالبًا ضمن الحدود. | | `احذف(فهرس)` | 1 | يحذف ويعيد العنصر، والخطأ عند فهرس غير صالح. | | `اسحب()` | 0 | يحذف ويعيد آخر عنصر، أو عدم لقائمة فارغة. | | `ادمج(فاصل?)` | 0–1 | يحوّل العناصر إلى نص ويصلها؛ الفاصل الافتراضي فارغ. | | `اعكس()` / `رتب(مقارن?)` | 0 / 0–1 | يعدّلان القائمة نفسها ويعيدانها؛ دالة المقارنة يجب أن تعيد رقمًا. | | `حول(دالة)` / `رشح(دالة)` | 1 | ينتجان قائمة جديدة بنتيجة الدالة أو بالعناصر التي تحقق شرطًا. | | `اطوي(دالة، بداية?)` | 1–2 | يختزل القائمة؛ من دون بداية، القائمة الفارغة خطأ. | | `نفذ(دالة)` | 1 | يستدعي الدالة على كل عنصر ويعيد عدم. | | `جد(دالة)` | 1 | يعيد أول عنصر تتحقق دالته، أو عدم. | | `اي(دالة)` / `كل(دالة)` | 1 | اختبار وجود عنصر صادق أو صدق جميع العناصر؛ يتوقف مبكرًا. | | `انسخ()` / `امسح()` | 0 | نسخ إلى قائمة جديدة أو إفراغ القائمة نفسها. | | `مجموع()` | 0 | يجمع الأرقام فقط؛ نوع غير رقمي يسبب خطأ. | | `ابحث(قيمة)` / `يحتوي(قيمة)` | 1 | موضع أول قيمة مساوية أو اختبار العضوية. | | `احصل(فهرس، افتراضي?)` | 1–2 | يعيد العنصر عند الفهرس أو القيمة الافتراضية/عدم. | | `اول()` / `اخر()` | 0 | أول/آخر عنصر أو عدم للقائمة الفارغة. | | `سطّح()` / `فريد()` | 0 | يفرد مستوى واحدًا من القوائم الداخلية أو يعيد العناصر الفريدة بترتيب الظهور. | | `جزء(بداية، نهاية?)` | 1–2 | يعيد شريحة جديدة بنهاية غير شاملة. | ## طرق القواميس **القواميس** | الاسم | الوسائط | السلوك المثبت | | --- | --- | --- | | `طول` | خاصية | عدد المفاتيح الحية. | | `مفاتيح()` / `قيم()` / `ازواج()` | 0 | قوائم المفاتيح أو القيم أو أزواج [مفتاح، قيمة]. | | `يحتوي(مفتاح)` | 1 | فحص وجود المفتاح. | | `احصل(مفتاح، افتراضي?)` | 1–2 | القيمة أو الافتراضي/عدم. | | `احذف(مفتاح)` | 1 | يحذف ويعيد القيمة السابقة، أو عدم. | | `انسخ()` / `امسح()` | 0 | نسخ قاموس أو إفراغ المستقبل وإعادته. | | `دمج(قاموس)` | 1 | يعدل القاموس المستقبل؛ قيم القاموس الممرر تستبدل المفاتيح نفسها. | الأسماء العربية في الجداول مطابقة لـ`src/vm/mids.inc`؛ حدود الوسائط وسلوك كل فرع مأخوذان من `src/vm/methods.inc`. ## حدود المرجع **مبادئ** > هذه الصفحة توثّق التسجيل والتنفيذ الظاهرين في المصدر. بعض التحويلات تعتمد على VM أو callbacks، ولم تُشغّل أمثلتها ضمن المهمة؛ تحقق من الصياغة على إصدارك بواسطة `solan --check`. ### Source files - src/vm/mids.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/mids.inc - src/vm/methods.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/methods.inc - src/vm/vm_run.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/vm_run.inc # Built-in Methods by Value Type — English ## Method availability depends on the receiver **Principles** `src/vm/mids.inc` registers Arabic method names, while `builtin_method` dispatches by receiver type: string, list, or map. A name in the global method table is not automatically available on all three types; unsupported receiver/method combinations are rejected. > Argument counts below are the source-enforced arity, not a complete type signature. Property-style methods such as `طول` are used without parentheses. ## String methods **Strings** | Name | Arguments | Source-confirmed behavior | | --- | --- | --- | | `طول` | property | UTF-8 character count. | | `قسم(separator?)` | 0–1 | Without a separator, splits on ASCII whitespace; empty separator splits characters; otherwise splits on the supplied string. | | `سطور()` | 0 | Returns lines; strips CR before LF. | | `نظف()` | 0 | Trims space, tab, LF, and CR at both ends. | | `كبير()` / `صغير()` | 0 | Changes ASCII a-z/A-Z only; does not implement Unicode case conversion for Arabic. | | `يبدأ_ب(text)` / `ينتهي_ب(text)` | 1 | Prefix or suffix check. | | `يحتوي(text)` | 1 | Substring check; the empty string is present. | | `ابدل(old, new)` | 2 | Replaces all non-overlapping matches; an empty old string returns the original. | | `جزء(start, end?)` | 1–2 | Character slice with exclusive end; bounds are clipped. | | `ابحث(text)` | 1 | Character offset of the match, or -1. | | `كرر(count)` | 1 | Repeats the string; count must be integral and output is capped at 512 MiB. | | `اعكس()` / `حروف()` | 0 | Reverses characters or returns a list of UTF-8 characters. | | `نسق(...)` | formatter-defined | Delegates to the source formatter. | | `املأ_يسار(width, pad?)` / `املأ_يمين(...)` | 1–2 | Pads with the supplied string (space by default) to the requested width. | > Length and offsets follow the source UTF-8 character helpers. `كبير` and `صغير` perform ASCII-only case conversion. ## List methods **Lists** | Name | Arguments | Source-confirmed behavior | | --- | --- | --- | | `طول` | property | Number of elements. | | `اضف(...items)` | 0+ | Mutates and returns the same list. | | `ادرج(index, value)` | 2 | Inserts at an index; negative indexes are accepted within bounds. | | `احذف(index)` | 1 | Removes and returns the element; invalid indexes raise an error. | | `اسحب()` | 0 | Pops the last element, or returns nil for an empty list. | | `ادمج(separator?)` | 0–1 | Converts items to strings and joins them; default separator is empty. | | `اعكس()` / `رتب(comparator?)` | 0 / 0–1 | Mutate and return the list; comparator must return a number. | | `حول(fn)` / `رشح(fn)` | 1 | Return a new mapped or filtered list. | | `اطوي(fn, initial?)` | 1–2 | Reduces the list; an empty list without an initial value is an error. | | `نفذ(fn)` | 1 | Calls the function for each element and returns nil. | | `جد(fn)` | 1 | Returns the first matching element, or nil. | | `اي(fn)` / `كل(fn)` | 1 | Tests whether any/all elements are truthy; short-circuits. | | `انسخ()` / `امسح()` | 0 | Copies to a new list or clears the receiver. | | `مجموع()` | 0 | Sums numbers only; a non-number raises an error. | | `ابحث(value)` / `يحتوي(value)` | 1 | Returns the first equal value index or tests membership. | | `احصل(index, default?)` | 1–2 | Returns the item at the index or the default/nil. | | `اول()` / `اخر()` | 0 | First/last item, or nil for an empty list. | | `سطّح()` / `فريد()` | 0 | Flattens one list level or returns unique items in encounter order. | | `جزء(start, end?)` | 1–2 | Returns a new slice with an exclusive end. | ## Map methods **Maps** | Name | Arguments | Source-confirmed behavior | | --- | --- | --- | | `طول` | property | Number of live keys. | | `مفاتيح()` / `قيم()` / `ازواج()` | 0 | Lists of keys, values, or `[key, value]` pairs. | | `يحتوي(key)` | 1 | Checks whether the key exists. | | `احصل(key, default?)` | 1–2 | Returns the value or default/nil. | | `احذف(key)` | 1 | Removes and returns the prior value, or nil. | | `انسخ()` / `امسح()` | 0 | Copies a map or clears and returns the receiver. | | `دمج(map)` | 1 | Mutates the receiver; incoming values replace matching keys. | Arabic names match `src/vm/mids.inc`; arity and behavior come from the corresponding branches in `src/vm/methods.inc`. ## Reference limits **Principles** > This page documents registration and implementation visible in the source. Some conversions depend on the VM or callbacks; examples were not executed in this task. Verify syntax on your installed version with `solan --check`. ### Source files - src/vm/mids.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/mids.inc - src/vm/methods.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/methods.inc - src/vm/vm_run.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/vm_run.inc # المكتبة القياسية المكتوبة بسولان — العربية ## 18 وحدة مكتوبة بسولان ومضمّنة **التعرّف على المكتبة** هذه الوحدات مكتوبة بسولان ومضمّنة داخل الملف التنفيذي؛ لا تحتاج تنزيلًا مستقلًا. استورد الوحدة باسمها ثم استخدم دوالها، مثل `استورد "نصوص"` ثم `نصوص.كلمات(نص)`. يمكن الاستعلام عن وجود وحدة بواسطة `نظام.مكتبة_قياسية("اسم")`. الوحدات الداخلية `حزم` و`خادم_اللغة` تنفذ أدوات التشغيل. | الوحدة | المجال والواجهات البارزة | | --- | --- | | `نصوص` | تطبيع العربية، قص وحشو النص، تحويل حالات الأسماء، تشابه ومسافة تحرير، باني نصوص. | | `مسارات` | تركيب وتحليل وتطبيع المسارات، فحص الاحتواء، glob والبحث. | | `مجموعات` | مجموعة فريدة، طابور، مكدس، deque، كومة أولوية، عدادات وتقسيم/تجميع القوائم. | | `عرض` | تنسيق الأرقام والأحجام والعملات والمدد والأعداد العربية؛ تفاصيلها أدناه. | | `تواريخ` | تاريخ ومدة وتقويم ميلادي/هجري وتنسيق ISO/strftime. | | `جداول` | CSV/TSV، رؤوس وأعمدة وفرز وتجميع وإحصاءات؛ تفصيل API أدناه. | | `قوالب` | قوالب نص/HTML، شروط وحلقات ومرشحات، وهروب HTML؛ تفاصيلها أدناه. | | `مخطط` | قواعد بيانات شكلية وفحصها وإرجاع أخطاء ذات مسارات. | | `نتيجة` | نوعا نتيجة/خيار وتحوّلات وأدوات تجميع وإعادة المحاولة. | | `ألوان` | ألوان الطرفية وANSI وإطارات وأشرطة تقدم وطول مرئي. | | `اختبار` | مجموعات واختبارات وخطافات وتأكيدات وmocks وتشغيل تقرير. | | `سجل` | مسجلات بمستويات متعددة، ملفات وتنسيق ومعالجات. | | `ذاكرة` | ذاكرة مؤقتة مع انتهاء اختياري وإحصاءات؛ تفاصيلها أدناه. | | `بث` | مرسل أحداث مع مستمعين لمرة واحدة أو مستمرين. | | `عمال` | عمليات عاملة وقنوات ووعود ومجمّع؛ تفاصيله أدناه. | | `وسائط` | تحليل خيارات سطر الأوامر والمساعدة وأوامر فرعية. | | `حزم` | إدارة manifest والقفل والاعتماديات والمتجر والتحقق. | | `خادم_اللغة` | خادم LSP عبر JSON-RPC وstdio. | > هذا الفهرس يميّز بين «واجهة موثقة في README» وبين signatures المستخرجة من تعريفات الملفات. الوحدات ليست كلها موثقة بالتفصيل نفسه؛ روابط المصدر لكل ملف ظاهرة أسفل الصفحة. ## واجهات بقية الوحدات **واجهات من README** | الوحدة | أسماء وواجهات يذكرها README | | --- | --- | | `نصوص` | `هل_فارغ`، `نظف_يسار/يمين`، `ازل_بادئة/لاحقة`، `اقتطع`، `كلمات`، `عد`، `املأ_يسار/يمين`، `وسّط`، `طبّع_عربي`، `هل_عربي`، `الى_هندية`، `مفكك`، `ثعباني`، `جمل`، `وصلة_رابط`، `مسافة`، `تشابه`، `اقرب`، `جديد`. | | `مسارات` | `ضم`، `الاسم`، `المجلد`، `الامتداد`، `طبّع_المسار`، `حلل`، `نسبي`، `هل_داخل`، `مطابق`، `ابحث`، `مجلد_مؤقت`. | | `مجموعات` | `مجموعة_من`، `طابور`، `مكدس`، `ثنائي_الطرف`، `كومة`، `عداد`، `دفعات`، `نوافذ`، `ازواج`، `جمّع`، `قسّم_حسب`، `عينة`، `ادمج_قواميس`. | | `تواريخ` | `انشئ`، `اجزاء`، `اضف`، `اطرح`، `فرق`، `بداية/نهاية_اليوم`، حدود الشهر/السنة/الأسبوع، `هل_كبيسة`، أسماء الأيام والشهور، ISO، و`الى_هجري`/`من_هجري`/`نص_هجري`. | | `مخطط` | `سلسلة`، `عدد`، `منطقي`، `قائمة_من`، `كائن`، `اي`، `صالح`، `افحص`، `افتح`. | | `نتيجة` | `نجاح`، `فشل`، `محاولة`، `اعد_المحاولة`، `تجميع`، `تجميع_اخطاء`، `شيء`، `غائب`، `من_قيمة`، `من_قاموس`، `من_قائمة`؛ وتحوّلات أعضاء نتيجة/خيار. | | `ألوان` | `اسود`/ألوان ANSI، `غامق`، `لون`، `لون256`، `rgb`، `هيكس`، `وسوم`، `ازل`، `طول_مرئي`، `اطار`، `شريط_تقدم`. | | `اختبار` | `مجموعة`، `اختبر`، `ارجئ`، `فقط`، hooks قبل/بعد، تأكيدات مساواة ونوع ومحتوى وخطأ، `وهمية`، `استدعيت_مرات`، `شغل_الكل`. | | `بث` | `جديد`؛ أعضاء الكائن: `على`، `مرة`، `الغ`، `امسح`، `ارسل`، `عدد_المستمعين`، `اسماء_الاحداث`. | | `وسائط` | `حلل`، `مساعدة`، `حلل_او_اخرج`، `حلل_اوامر`، `مساعدة_اوامر`. | > هذا فهرس أسماء من README وليس تأكيدًا لتواقيع كل وسيط/نوع أو كل فرع تنفيذي. انظر الملفات المصدرية المرتبطة للتحقق من نسخة الفرع الحالية. ## جداول: CSV وTSV **واجهات مفصلة من ملفات المصدر** | التوقيع | السلوك من المصدر | | --- | --- | | `كشف_فاصل(نص)` | يفحص أول سطر ويختار الأكثر ظهورًا بين `,` و`;` وtab و`\|`؛ التعادل يحتفظ بأول فاصل. | | `حلل(نص، فاصل=",")` | يفك صفوفًا وحقولًا مقتبسة وتهريب الاقتباس المزدوج؛ LF ينهي صفًا وCR يُتجاهل. | | `حلل_رؤوس(نص، فاصل=",")` | يستعمل الصف الأول رؤوسًا، ويملأ الخانات الناقصة بنص فارغ. | | `حول_انواع(قواميس)` | ينشئ قواميس جديدة ويحوّل النصوص الرقمية والمنطقية وفق قواعد `_قيمة`. | | `كتب(صفوف، فاصل=",")` | يكتب صفوفًا؛ يقتبس الخلية ويكرر الاقتباس داخل الحقل عند الحاجة. | | `اعمدة(قواميس)` | يجمع مفاتيح القواميس بترتيب أول ظهور دون تكرار. | | `كتب_قواميس(قواميس، رؤوس=عدم، فاصل=",")` | يكتب الرؤوس والصفوف وفق الأعمدة. | | `اقرا(مسار، فاصل=عدم)` | يقرأ ملفًا ويفك الرؤوس؛ يستنتج الفاصل إذا لم يحدد. يعتمد على `ملفات`. | | `احفظ(مسار، بيانات، فاصل=",")` | يكتب صفوفًا أو قواميس إلى ملف؛ يعتمد على `ملفات`. | | `حلل_tsv(نص)` / `كتب_tsv(قواميس)` | اختصارات لفاصل tab. | | `اختر(قواميس، أعمدة)` | ينشئ قواميس تحتوي المفاتيح المطلوبة فقط. | | `رتب_حسب(قواميس، عمود، تنازلي=غلط)` | يرتب نسخة حسب قيمة عمود؛ السلوك للأنواع غير المتجانسة غير محدد هنا. | | `جمّع_حسب(قواميس، عمود)` / `فريد_حسب(قواميس، عمود)` | تجميع حسب قيمة العمود أو إبقاء أول قاموس لكل قيمة. | | `مجموع` / `متوسط` / `اعلى` / `ادنى`(قواميس، عمود) | إحصاءات على القيم الرقمية فقط؛ متوسط/أعلى/أدنى تعيد عدم عند انعدامها. | | `عمود(قواميس، عمود)` | يعيد قيم العمود. | | `اعرض(بيانات، رؤوس=عدم، حد=40)` | ينشئ جدول طرفية بمحاذاة الأرقام ويقتطع الخلايا حسب الحد. يعتمد على `ألوان` و`نصوص`. | > لا يرفض المصدر صراحةً اقتباسًا غير مغلق أو حقول بيانات زائدة عن عدد الرؤوس؛ لا تفترض سياسة تحقق لم يذكرها. لم تُشغّل هذه الدوال خلال إعداد الصفحة. ## حزم وخادم اللغة **واجهات مفصلة من ملفات المصدر** الوحدتان داخليتان وتشغّلان أدوات Solan. لا توجد في الملفات التي فُحصت تصريحات export صريحة؛ التواقيع التالية وصف لتعريفات المصدر، وليست وعدًا بأن كل دالة متاحة لاستيراد البرامج العادية. | المصدر | التوقيع / الحد | | --- | --- | | `حزم` | `البيان="solan.json"`، `القفل="solan.lock"`؛ حدود المصدر: 5000 ملف، 50 MiB، 500 اعتماد، 500 جذر مشروع. | | `بصمة(مجلد)` | يجمع الملفات، يتجاهل .git و.solan-meta، يرفض symlinks، ويحسِب SHA-256؛ قد يرفع أخطاء العدد/الحجم/الملفات. | | `ثبت_الكل(مجمد=غلط، صامت=غلط، محلي=غلط)` | يحل البيان والقفل ويثبت الاعتماديات؛ المجمد يتطلب قفلًا صالحًا ويطابق البصمات. | | `اضف(نص، اسم=عدم)` | يحدّث الاعتماد ثم يثبت؛ يعيد القيمة السابقة أو يحذف الاعتماد إذا فشل التثبيت. | | `احذف(اسم)` | يحذف اعتمادًا من البيان ويعيد بناء القفل؛ لا يحذف الحزمة من المتجر. | | `حدّث(اسم=عدم، رئيسي=غلط)` | يعيد حل اعتماد واحد أو الجميع؛ قد يغيّر نطاق إصدار Git عند `رئيسي`. | | `اعرض(شجرة=غلط، مخزن=غلط)` / `لماذا(اسم)` / `قديمة()` | يعرض الاعتمادات، شجرة الاعتمادات أو المتجر، مصدر اعتماد، أو تحديثات متاحة. | | `تحقق()` / `نظف_المتجر(تجربة=غلط)` / `نظف_الكاش()` | فحص بصمات القفل، إزالة الاعتمادات غير المستخدمة (أو عرضها تجريبيًا)، ومسح التنزيلات المؤقتة. | | `بدء(مكتبة=غلط)` / `انشر(تجربة=غلط، ادفع=غلط)` | تهيئة مشروع/مكتبة، والتحقق من إصدار ووسم git؛ تجربة النشر لا تنشئ وسمًا. | | `خادم_اللغة.شغل()` | حلقة JSON-RPC/LSP؛ تعلن مزامنة كاملة وcompletion عند النقطة وhover وتعريف ورموز المستند، وتعالج رسائل المستند والتشخيص. | > تعتمد وحدة حزم على git وملفات/JSON/النظام والتشفير؛ حزم Git لا تملك توقيعًا رقميًا وفق README، وتتحقق السلامة بواسطة commit وSHA-256 في القفل. راجع صفحة الأمان. ## الذاكرة والسجل والعرض **واجهات مفصلة من ملفات المصدر** | الواجهة | السلوك الموثق في المصدر | | --- | --- | | `ذاكرة.جديد(سعة=0، عمر=0)` | ينشئ ذاكرة بمخزن وسعته وعمر افتراضيين؛ الصفر لا يطبّق الإخلاء/الانتهاء. | | `ذاكرة_مؤقتة.ضع(مفتاح، قيمة، عمر=عدم)` | يخزن قيمة ووقت انتهاء اختياريًا؛ عند تجاوز سعة موجبة يزيل أول مفتاح في مخزن القاموس. | | `خذ(مفتاح، افتراضي=عدم)` / `يوجد(مفتاح)` | قراءة مع انتهاء lazy؛ خذ يزيد عدادي الإصابة/الإخفاق، ويوجد لا يحذف ولا يغير العدادات. | | `احذف` / `امسح` / `نظف` / `حجم` / `مفاتيح` | حذف/إفراغ/تنظيف المنتهيات/قياس الحجم/عرض المفاتيح. امسح لا يصفر إحصاءات الإصابة. | | `احسب(مفتاح، دالة، عمر=عدم)` / `احصائيات()` | يحسب عند عدم وجود قيمة صالحة؛ الإحصاءات تتضمن إصابات وإخفاقات ونسبتها والحجم. | | `ذاكرة.احفظ_نتيجة(دالة، عمر=0، سعة=0)` | يعيد دالة مغلقة على ذاكرة مؤقتة لنتائج الدالة. | | `سجل.مستوى(م)` / `ملف(مسار)` / `صيغة(ص)` | يضبط المستوى أو مسار الإخراج أو صيغة النص/JSON. أسماء المستويات: تصحيح=10، معلومة=20، تحذير=30، خطأ=40، حرج=50. | | `اضف_معالج(دالة)` / `امسح_المعالجات()` | إدارة معالجات تُستدعى بكائن يحوي المستوى والرسالة والمسجل والحقول والسطر. | | `سجل.جديد(اسم="", حقول={})` | ينشئ مسجلًا؛ طرقه تصحيح/معلومة/تحذير/خطأ/حرج، `مع(حقول)` و`فرعي(اسم)`. | | `سجل(مستوى، ...قيم)` والطرق المختصرة | `تصحيح`، `معلومة`، `تحذير`، `خطأ`، `حرج`؛ يتجاهل المستوى الأقل من الحد المضبوط. | | `عرض.ارقام_مفصولة(ن، فاصل=","، عشري=عدم)` | تنسيق مجموعات الأرقام؛ الأعداد العلمية تبقى بصيغتها النصية. | | `حجم_ملف(بايت، عشري=1، عربي=غلط)` / `نسبة(ق، عشري=1)` / `عملة(ق، رمز=""، عشري=2)` | تنسيق أحجام بوحدات 1024 والنسب والعملات. | | `عدد_معدود(ن، مفرد، مثنى، جمع، كثير=عدم)` | اختيار صيغة عربية حسب العدد. | | `مدة(ثواني، حد=2)` / `مدة_قصيرة(ثواني)` | تفكيك المدة إلى وحدات نصية طويلة أو مختصرة. | | `عدد_بالحروف(ن)` | تحويل عدد إلى كلمات عربية؛ المصدر يرمي «العدد كبير جدا» عند تجاوز جدول المقاييس. | > لا يفرض ملف الذاكرة ترتيبًا مستقرًا لمفاتيح القاموس عند الإخلاء، ولا يوضح أنواع المدخلات أو أخطاء callback. استخدم صفحة المصدر للتحقق من تفاصيل إصدارك. ## العمال والقوالب **واجهات مفصلة من ملفات المصدر** | الواجهة | السلوك الموثق في المصدر | | --- | --- | | `عمال.انشئ(دالة)` | ينشئ عامل عملية معزولة وقناة JSON سطرية، ويعيد كائن عامل. | | `عامل.اطلب(رسالة)` | يرسل طلبًا بمعرف متزايد ويعيد وعدًا؛ الرد يحل قيمة أو يرفض بخطأ، وEOF يرفض الوعود المنتظرة. | | `عامل.ارسل(رسالة)` / `استقبل()` / `عند_رسالة(دالة)` / `انهِ()` | إرسال/استقبال، معالج الرسائل غير المرتبطة بطلب، وإنهاء العملية والسوكت. | | `عمال.خادم_طلبات(معالج)` | يعالج الرسائل في حلقة ويرسل نتيجة أو نص الخطأ المقابل للطلب. | | `عمال.مجمع_جديد(عدد، معالج)` | ينشئ مجموعة عمال بعدد محدد ويهيئ عداد انشغال لكل عامل. | | `مجمع.نفذ(بيانات)` / `حول(قائمة)` / `اغلق()` | يوزع العمل على الأقل انشغالًا، يعيد Promise للعمل المفرد أو قائمة نتائج متوازية، ثم يغلق العمال. | | `قوالب.هرب_html(نص)` | يهرب & و< و> والاقتباس المزدوج والمفرد إلى كيانات HTML. | | `قوالب.صرّف(نموذج)` | يحوّل القالب إلى شجرة رموز؛ يتحقق من إغلاق #اذا/#لكل ويرمي عند الصياغة غير المتوازنة. | | `قوالب.ارسم(نموذج، بيانات={ }، هرب=غلط)` | يرسم نصًا أو شجرة؛ يفهم `{{...}}` والمتغيرات والمسارات والمرشحات والشروط والحلقات. | | `قوالب.ارسم_html(نموذج، بيانات={ })` | مثل ارسم مع تفعيل هروب HTML للقيم غير الخام. | - في قالب القوالب، `{{اسم}}` يقرأ قيمة، و`{{{اسم}}}` وسم خام وفق الصياغة التي يتعرف عليها القاطع. `{{#اذا ...}}` و`{{#لكل ...}}` يدعمان شرطًا/حلقة و`والا`. - يعالج المجمّع العامل الرسائل باستخدام JSON لكل سطر. لا تفترض ترتيب مفاتيح القواميس أو وجود مصدر لوعود العمال غير المستورد دون الرجوع إلى ملفات البيئة. ## الاعتمادات وحدود الثقة **التعرّف على المكتبة** التحليل التفصيلي لثماني ملفات في هذه الصفحة اعتمد على تعريفات المصدر: `جداول` و`حزم` و`خادم_اللغة` و`ذاكرة` و`سجل` و`عرض` و`عمال` و`قوالب`. بقية الوحدات مدرجة من جرد README، مع وصلات إلى ملفاتها مباشرة. - الأمثلة الواردة في README أو المقتطفات الإيضاحية هنا لم تُشغّل ضمن هذه المهمة؛ لا تتعامل معها كاختبارات تنفيذية. - لا تظهر في عدة ملفات تصريحات export صريحة أو أنواع معاملات/إرجاع؛ التوثيق لا يستنتج تلك العقود. - قد تستورد الوحدات الأخرى مثل `ملفات` و`جيسون` و`نظام` و`زمن` و`ألوان` و`نصوص`، أو تعتمد على builtins للغة. - للتثبيت وأوامر CLI انظر الصفحات المخصصة؛ هذه الصفحة لا تكرر تعليمات التثبيت. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - src/vm/stdlib_embed.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/stdlib_embed.inc - stdlib/ألوان.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%A3%D9%84%D9%88%D8%A7%D9%86.%D8%B3%D9%88 - stdlib/اختبار.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1.%D8%B3%D9%88 - stdlib/بث.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%A8%D8%AB.%D8%B3%D9%88 - stdlib/تواريخ.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AA%D9%88%D8%A7%D8%B1%D9%8A%D8%AE.%D8%B3%D9%88 - stdlib/جداول.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AC%D8%AF%D8%A7%D9%88%D9%84.%D8%B3%D9%88 - stdlib/حزم.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AD%D8%B2%D9%85.%D8%B3%D9%88 - stdlib/خادم_اللغة.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AE%D8%A7%D8%AF%D9%85_%D8%A7%D9%84%D9%84%D8%BA%D8%A9.%D8%B3%D9%88 - stdlib/ذاكرة.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%B0%D8%A7%D9%83%D8%B1%D8%A9.%D8%B3%D9%88 - stdlib/سجل.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%B3%D8%AC%D9%84.%D8%B3%D9%88 - stdlib/عرض.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%B9%D8%B1%D8%B6.%D8%B3%D9%88 - stdlib/عمال.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%B9%D9%85%D8%A7%D9%84.%D8%B3%D9%88 - stdlib/قوالب.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%82%D9%88%D8%A7%D9%84%D8%A8.%D8%B3%D9%88 - stdlib/مجموعات.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%85%D8%AC%D9%85%D9%88%D8%B9%D8%A7%D8%AA.%D8%B3%D9%88 - stdlib/مخطط.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%85%D8%AE%D8%B7%D8%B7.%D8%B3%D9%88 - stdlib/مسارات.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%85%D8%B3%D8%A7%D8%B1%D8%A7%D8%AA.%D8%B3%D9%88 - stdlib/نتيجة.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%86%D8%AA%D9%8A%D8%AC%D8%A9.%D8%B3%D9%88 - stdlib/نصوص.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%86%D8%B5%D9%88%D8%B5.%D8%B3%D9%88 - stdlib/وسائط.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%88%D8%B3%D8%A7%D8%A6%D8%B7.%D8%B3%D9%88 # Solan Standard Library — English ## 18 Solan-written modules bundled with the executable **Library overview** These modules are written in Solan and bundled in the executable; they do not need separate installation. Import a module by name, then call its functions—for example, `استورد "نصوص"` followed by `نصوص.كلمات(text)`. Check availability with `نظام.مكتبة_قياسية("name")`. The internal `حزم` and `خادم_اللغة` modules power runtime tools. | Module | Area and notable API | | --- | --- | | `نصوص` | Arabic normalization, trimming/padding, case conversion, similarity/edit distance, string builder. | | `مسارات` | Join, parse, normalize and inspect paths; containment, glob and search. | | `مجموعات` | Set, queue, stack, deque, priority queue, counters and list grouping utilities. | | `عرض` | Formatting numbers, sizes, currency, durations, and Arabic number words; details below. | | `تواريخ` | Date/time arithmetic, Gregorian/Hijri calendar, ISO and strftime. | | `جداول` | CSV/TSV, headers/columns, sort/group/statistics; API details below. | | `قوالب` | Text/HTML templates with conditions, loops, filters, and HTML escaping; details below. | | `مخطط` | Data-shape rules, validation, and path-aware errors. | | `نتيجة` | Result/Option types, transformations, collection, and retry helpers. | | `ألوان` | Terminal ANSI colors, frames, progress bars, visible width. | | `اختبار` | Suites, tests, hooks, assertions, mocks, and test reports. | | `سجل` | Level-based loggers, files, formats, and custom handlers. | | `ذاكرة` | Cache with optional expiry and statistics; details below. | | `بث` | Event emitter with persistent or one-shot listeners. | | `عمال` | Worker processes, channels, promises, and pools; details below. | | `وسائط` | Command-line option parsing, help, and subcommands. | | `حزم` | Manifest/lock/dependency/store management and verification. | | `خادم_اللغة` | JSON-RPC/stdio LSP server. | > This index distinguishes README-documented APIs from signatures extracted directly from module definitions. Not every module has the same level of detail here; each source file is linked below. ## Other module APIs **README API index** | Module | API names documented in README | | --- | --- | | `نصوص` | `هل_فارغ`, `نظف_يسار/يمين`, `ازل_بادئة/لاحقة`, `اقتطع`, `كلمات`, `عد`, `املأ_يسار/يمين`, `وسّط`, `طبّع_عربي`, `هل_عربي`, `الى_هندية`, `مفكك`, `ثعباني`, `جمل`, `وصلة_رابط`, `مسافة`, `تشابه`, `اقرب`, `جديد`. | | `مسارات` | `ضم`, `الاسم`, `المجلد`, `الامتداد`, `طبّع_المسار`, `حلل`, `نسبي`, `هل_داخل`, `مطابق`, `ابحث`, `مجلد_مؤقت`. | | `مجموعات` | `مجموعة_من`, `طابور`, `مكدس`, `ثنائي_الطرف`, `كومة`, `عداد`, `دفعات`, `نوافذ`, `ازواج`, `جمّع`, `قسّم_حسب`, `عينة`, `ادمج_قواميس`. | | `تواريخ` | `انشئ`, `اجزاء`, `اضف`, `اطرح`, `فرق`, day/month/year/week boundaries, leap-year checks, Arabic names, ISO, and Hijri conversion helpers. | | `مخطط` | `سلسلة`, `عدد`, `منطقي`, `قائمة_من`, `كائن`, `اي`, `صالح`, `افحص`, `افتح`. | | `نتيجة` | `نجاح`, `فشل`, `محاولة`, `اعد_المحاولة`, `تجميع`, `تجميع_اخطاء`, `شيء`, `غائب`, `من_قيمة`, `من_قاموس`, `من_قائمة`, plus Result/Option methods. | | `ألوان` | ANSI color names, `غامق`, `لون`, `لون256`, `rgb`, `هيكس`, `وسوم`, `ازل`, `طول_مرئي`, `اطار`, `شريط_تقدم`. | | `اختبار` | `مجموعة`, `اختبر`, `ارجئ`, `فقط`, before/after hooks, equality/type/content/error assertions, `وهمية`, call-count helpers, `شغل_الكل`. | | `بث` | `جديد`; object methods: `على`, `مرة`, `الغ`, `امسح`, `ارسل`, `عدد_المستمعين`, `اسماء_الاحداث`. | | `وسائط` | `حلل`, `مساعدة`, `حلل_او_اخرج`, `حلل_اوامر`, `مساعدة_اوامر`. | > This is a README name index, not a complete contract for every argument type or implementation branch. Check the linked source files for the current branch. ## جداول: CSV and TSV **Detailed source-derived APIs** | Signature | Source-derived behavior | | --- | --- | | `كشف_فاصل(text)` | Counts delimiters on the first line among comma, semicolon, tab, and pipe; ties keep the first candidate. | | `حلل(text, separator=",")` | Parses rows and quoted fields, including doubled quote escaping; LF ends a row and CR is ignored. | | `حلل_رؤوس(text, separator=",")` | Uses the first row as headers and fills missing cells with an empty string. | | `حول_انواع(maps)` | Returns new maps and converts string values using `_قيمة` rules. | | `كتب(rows, separator=",")` | Writes rows, quoting cells and doubling embedded quotes when needed. | | `اعمدة(maps)` | Collects map keys in first-seen order without duplicates. | | `كتب_قواميس(maps, headers=عدم, separator=",")` | Writes a header row and rows by column order. | | `اقرا(path, separator=عدم)` | Reads a file and parses header maps; detects a separator when omitted. Depends on `ملفات`. | | `احفظ(path, data, separator=",")` | Writes rows or maps to a file; depends on `ملفات`. | | `حلل_tsv(text)` / `كتب_tsv(maps)` | Tab-separated shortcuts. | | `اختر(maps, columns)` | Returns new maps containing selected keys. | | `رتب_حسب(maps, column, descending=غلط)` | Sorts a copy by a column; mixed-type comparison behavior is not specified here. | | `جمّع_حسب(maps, column)` / `فريد_حسب(maps, column)` | Groups by column value or keeps the first map per value. | | `مجموع` / `متوسط` / `اعلى` / `ادنى(maps, column)` | Statistics over numeric values; mean/min/max return nil when none are available. | | `عمود(maps, column)` | Returns values from a column. | | `اعرض(data, headers=عدم, limit=40)` | Formats a terminal table, aligns numeric values, and truncates cells. Depends on `ألوان` and `نصوص`. | > The source does not explicitly reject an unclosed quote or extra data fields beyond header count; do not assume validation it does not specify. These functions were not executed while preparing this page. ## Packages and language server **Detailed source-derived APIs** These internal modules power Solan tools. The inspected files have no explicit export declarations; the signatures below describe source definitions, not a promise that every function is importable by ordinary programs. | Module | Signature / limit | | --- | --- | | `حزم` | `البيان="solan.json"`, `القفل="solan.lock"`; source limits: 5,000 files, 50 MiB, 500 dependencies, 500 registered project roots. | | `بصمة(directory)` | Collects files, ignores .git and .solan-meta, rejects symlinks, computes SHA-256; may raise file/count/size errors. | | `ثبت_الكل(frozen=غلط, quiet=غلط, local=غلط)` | Resolves manifest/lock and installs dependencies; frozen mode requires a valid lock and checks hashes. | | `اضف(spec, name=عدم)` | Updates dependency and installs; restores/removes the dependency if installation fails. | | `احذف(name)` | Removes a dependency from the manifest and rebuilds the lock; does not remove it from the shared store. | | `حدّث(name=عدم, major=غلط)` | Resolves one/all dependencies; can change a Git version range with `major`. | | `اعرض(tree=غلط, store=غلط)` / `لماذا(name)` / `قديمة()` | Lists dependencies, tree/store, dependency provenance, or available updates. | | `تحقق()` / `نظف_المتجر(dry_run=غلط)` / `نظف_الكاش()` | Checks lock hashes, removes unused packages (or previews), and clears temporary downloads. | | `بدء(library=غلط)` / `انشر(dry_run=غلط, push=غلط)` | Initializes project/library and validates release tags; dry-run does not create a tag. | | `خادم_اللغة.شغل()` | JSON-RPC/LSP loop; advertises full sync, dot-triggered completion, hover, definition, document symbols, and document/diagnostic messages. | > The package module depends on git, files/JSON/system, and hashing. Git packages have no digital signature in README; integrity uses the locked commit and SHA-256. See the security page. ## Cache, logging, and formatting **Detailed source-derived APIs** | API | Source-described behavior | | --- | --- | | `ذاكرة.جديد(capacity=0, age=0)` | Creates a cache; zero means no capacity eviction/expiry. | | `ذاكرة_مؤقتة.ضع(key, value, age=عدم)` | Stores a value and optional expiry; once a positive capacity is exceeded, removes the first key returned by the backing map. | | `خذ(key, default=عدم)` / `يوجد(key)` | Lazy expiry; `خذ` updates hit/miss counters, while `يوجد` neither deletes nor changes counters. | | `احذف` / `امسح` / `نظف` / `حجم` / `مفاتيح` | Delete/clear/clean expired/measure/list keys. Clear does not reset hit statistics. | | `احسب(key, fn, age=عدم)` / `احصائيات()` | Computes on a cache miss; statistics include hits, misses, hit ratio, and size. | | `ذاكرة.احفظ_نتيجة(fn, age=0, capacity=0)` | Returns a function closed over a result cache. | | `سجل.مستوى(level)` / `ملف(path)` / `صيغة(format)` | Sets threshold, output path, or text/JSON format. Levels: debug=10, info=20, warning=30, error=40, critical=50. | | `اضف_معالج(fn)` / `امسح_المعالجات()` | Manage handlers receiving a record with level, message, logger, fields, and line. | | `سجل.جديد(name="", fields={})` | Creates a logger with level methods, `مع(fields)`, and `فرعي(name)`. | | `سجل(level, ...values)` and shortcuts | `تصحيح`, `معلومة`, `تحذير`, `خطأ`, `حرج`; messages below the configured threshold are ignored. | | `عرض.ارقام_مفصولة(n, separator=",", decimals=عدم)` | Formats digit groups; scientific-number strings are preserved. | | `حجم_ملف(bytes, decimals=1, Arabic=غلط)` / `نسبة` / `عملة` | Formats 1024-based sizes, percentages, and currency. | | `عدد_معدود(n, singular, dual, plural, many=عدم)` | Selects an Arabic noun form based on number. | | `مدة(seconds, limit=2)` / `مدة_قصيرة(seconds)` | Formats durations in long or compact units. | | `عدد_بالحروف(n)` | Converts a number to Arabic words; raises “العدد كبير جدا” past the scale table. | > The cache source does not guarantee map-key order for eviction or specify argument types/callback error handling. Check the linked source for your version. ## Workers and templates **Detailed source-derived APIs** | API | Source-described behavior | | --- | --- | | `عمال.انشئ(fn)` | Creates an isolated worker process and line-oriented JSON channel; returns a worker object. | | `عامل.اطلب(message)` | Sends an incrementing request ID and returns a promise; replies resolve a value or reject with an error; EOF rejects pending promises. | | `عامل.ارسل(message)` / `استقبل()` / `عند_رسالة(fn)` / `انهِ()` | Send/receive, handle unsolicited messages, and close the worker/socket/process. | | `عمال.خادم_طلبات(handler)` | Runs a request loop and sends a result or error string for each request. | | `عمال.مجمع_جديد(count, handler)` | Creates a pool of the requested size and initializes per-worker busy counters. | | `مجمع.نفذ(data)` / `حول(list)` / `اغلق()` | Dispatches to a least-busy worker, returns a promise or parallel results, then closes workers. | | `قوالب.هرب_html(text)` | Escapes &, <, >, double quote, and single quote to HTML entities. | | `قوالب.صرّف(template)` | Parses a template into tokens; checks `#اذا`/`#لكل` closure and errors on unbalanced syntax. | | `قوالب.ارسم(template, data={}, escape=غلط)` | Renders text or a token tree with `{{...}}`, paths, filters, conditions, and loops. | | `قوالب.ارسم_html(template, data={})` | Same as render but enables HTML escaping for non-raw values. | - Template syntax includes `{{name}}`, a raw form recognized by the tokenizer, and `{{#اذا ...}}` / `{{#لكل ...}}` blocks with `والا`. - Worker requests use JSON per line. Do not assume map key order or the origin of worker promises without checking runtime sources. ## Dependencies and accuracy boundaries **Library overview** Detailed source inspection in this page covers eight files: `جداول`, `حزم`, `خادم_اللغة`, `ذاكرة`, `سجل`, `عرض`, `عمال`, and `قوالب`. Other modules are indexed from README with direct links to their files. - README and illustrative samples here were not executed as part of this task; they are not execution tests. - Several files have no explicit export declarations or argument/return types; this reference does not invent those contracts. - Modules may depend on other modules such as `ملفات`, `جيسون`, `نظام`, `زمن`, `ألوان`, `نصوص`, or language built-ins. - See the dedicated pages for installation and CLI instructions; they are not duplicated here. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - src/vm/stdlib_embed.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/stdlib_embed.inc - stdlib/ألوان.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%A3%D9%84%D9%88%D8%A7%D9%86.%D8%B3%D9%88 - stdlib/اختبار.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%A7%D8%AE%D8%AA%D8%A8%D8%A7%D8%B1.%D8%B3%D9%88 - stdlib/بث.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%A8%D8%AB.%D8%B3%D9%88 - stdlib/تواريخ.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AA%D9%88%D8%A7%D8%B1%D9%8A%D8%AE.%D8%B3%D9%88 - stdlib/جداول.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AC%D8%AF%D8%A7%D9%88%D9%84.%D8%B3%D9%88 - stdlib/حزم.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AD%D8%B2%D9%85.%D8%B3%D9%88 - stdlib/خادم_اللغة.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AE%D8%A7%D8%AF%D9%85_%D8%A7%D9%84%D9%84%D8%BA%D8%A9.%D8%B3%D9%88 - stdlib/ذاكرة.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%B0%D8%A7%D9%83%D8%B1%D8%A9.%D8%B3%D9%88 - stdlib/سجل.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%B3%D8%AC%D9%84.%D8%B3%D9%88 - stdlib/عرض.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%B9%D8%B1%D8%B6.%D8%B3%D9%88 - stdlib/عمال.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%B9%D9%85%D8%A7%D9%84.%D8%B3%D9%88 - stdlib/قوالب.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%82%D9%88%D8%A7%D9%84%D8%A8.%D8%B3%D9%88 - stdlib/مجموعات.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%85%D8%AC%D9%85%D9%88%D8%B9%D8%A7%D8%AA.%D8%B3%D9%88 - stdlib/مخطط.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%85%D8%AE%D8%B7%D8%B7.%D8%B3%D9%88 - stdlib/مسارات.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%85%D8%B3%D8%A7%D8%B1%D8%A7%D8%AA.%D8%B3%D9%88 - stdlib/نتيجة.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%86%D8%AA%D9%8A%D8%AC%D8%A9.%D8%B3%D9%88 - stdlib/نصوص.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%86%D8%B5%D9%88%D8%B5.%D8%B3%D9%88 - stdlib/وسائط.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D9%88%D8%B3%D8%A7%D8%A6%D8%B7.%D8%B3%D9%88 # المكتبات الأصلية المدمجة — العربية ## ما المقصود بالمكتبات الأصلية؟ **التحميل والاستخدام** هي وحدات تبنى داخل ملف Solan التنفيذي وليست حزمًا خارجية. يستورد البرنامج الوحدة بصيغة `استورد "اسم"`. وفق README، الوحدات المتاحة دائمًا دون استيراد صريح هي `نظام` و`جيسون` و`شبكة` و`سوكت` و`حلقة`؛ وتُستورد الوحدات الأخرى قبل استعمالها. | الوحدة | المجال | | --- | --- | | `رياضيات`، `ضخم`، `عشوائي`، `زمن` | حسابات وأعداد صحيحة كبيرة وعشوائية ووقت. | | `نظام`، `ملفات`، `جيسون`، `نمط` | البيئة والعمليات والملفات وJSON والتعابير النمطية. | | `تشفير`، `ضغط` | بصمات وHMAC وBase64/hex وgzip/zlib. | | `شبكة`، `سوكت`، `ويبسوكت`، `حلقة` | HTTP/TLS، TCP/UDP، WebSocket، ومراقبة الأحداث والمؤقتات. | | `قاعدة`، `ffi` | SQLite واستدعاء مكتبات C أو تحميل وحدات أصلية. | ## HTTP وخادم الويب **الشبكات** | الدالة | ما تعيده أو تفعله | | --- | --- | | `شبكة.جلب(رابط، خيارات?)` | طلب HTTP/HTTPS حاجب؛ يعيد قاموسًا يحوي الحالة والجسم والرؤوس وناجح والرابط. خياراته تشمل الطريقة والرؤوس والجسم والمهلة والتحويلات وTLS والنماذج. | | `شبكة.جلب_متدفق(رابط، callback، خيارات?)` | يستدعي callback لأجزاء النقل قبل اكتمال الرد، ثم يعيد قاموس الاستجابة المعتاد. الاستدعاء نفسه متزامن وحاجب. | | `شبكة.خادم(منفذ، معالج، خيارات?)` | خادم HTTP حاجب؛ المعالج يستقبل قاموس الطلب. إرجاع نص ينشئ HTML، وإرجاع قاموس يدعم حالة ورؤوس وجسمًا. | | `شبكة.خادم_حلقة(...)` | خادم HTTP على حلقة الأحداث؛ يسمح بمعالج غير متزامن. | | `شبكة.ترميز_رابط(نص)` / `فك_رابط(نص)` | ترميز وفك مكوّنات الرابط. | | `شبكة.اقرا_طلب(...)` / `اكتب_رد(...)` | واجهات منخفضة المستوى لمعالجة HTTP فوق السوكت. | > في `جلب_متدفق` قد ينقسم حدث SSE أو محرف UTF-8 بين جزأين؛ ابنِ مخزنًا في التطبيق وأعد تجميع البيانات قبل تحليل الحدث أو فك النص. الفشل بعد وصول بيانات جزئية يرمي خطأ ولا يعيد ردًا جزئيًا كمكتمل. > HTTPS وWSS يتطلبان OpenSSL وقت التشغيل في الإعداد الموصوف بالـREADME؛ بدون TLS تعمل الشبكات العادية HTTP/TCP فقط. لا تعطّل التحقق من شهادة TLS إلا لسبب معلوم. ## TCP وUDP وWebSocket وحلقة الأحداث **الشبكات** - `سوكت` يوفر استماعًا وقبولًا واتصالًا وإرسالًا وقراءة محدودة أو دقيقة أو سطرية، ومهلًا ووضعًا غير حاجب وانتظار الجاهزية وDNS وواجهات UDP وإغلاق المقبض. - `ويبسوكت` يتصل بـ`ws://` أو `wss://`، يرقّي طلب HTTP واردًا، ويرسل/يستقبل رسائل وping ويغلق القناة. - `حلقة` تعمل على خيط واحد بلا خيوط؛ فيها مؤقتات لمرة واحدة ومتكررة، ومراقبة المقابض، وخطوة وتشغيل وإيقاف. **أنماط استدعاء واردة في README (لم تُعد تجربتها)** ```solan خل مقبض = سوكت.اتصل("localhost", 9000) سوكت.ارسل(مقبض, "مرحبا") خل م = حلقة.كل(1, دالة() { اطبع("tick") }) حلقة.الغ(م) ``` ## JSON وRegex وSQLite والضغط والتشفير **البيانات والتشفير** | الوحدة | الواجهات والسلوك الموثق | | --- | --- | | `جيسون` | `ترميز(قيمة، مسافة?)` يحول قيمة إلى JSON؛ `فك(نص)` يحلل JSON ويمثل null بـ`عدم`. | | `نمط` | `ابحث` و`هل` و`مطابق_كامل` و`كل` و`قسم` و`ابدل`؛ يدعم مجموعات مسماة وخيارات تجاهل الحالة والتطبيع متعدد الأسطر ونقطة السطر. | | `قاعدة` | `افتح` و`نفذ` و`استعلم` و`اغلق`؛ استعلام SELECT يعيد قائمة قواميس. مرّر القيم في قائمة علامات `?` بدل إدراجها نصيًا لتجنب حقن SQL. | | `ضغط` | `gzip` و`gunzip` و`zlib` و`فك`؛ الضغط الأساسي مضمن، وسقف المخرجات الموصوف 512 MiB لحماية فك الضغط. | | `تشفير` | `sha256` و`sha1` و`hmac_sha256` و`base64`/`فك_base64` و`hex`/`فك_hex` و`عشوائي_بايتات`. | **مثال SQLite من README (غير مُعاد تشغيله)** ```solan استورد "قاعدة" خل ق = قاعدة.افتح("t.db") قاعدة.نفذ(ق, "INSERT INTO ت VALUES (?, ?)", [1, "س"]) خل صفوف = قاعدة.استعلم(ق, "SELECT * FROM ت WHERE ا = ?", [1]) قاعدة.اغلق(ق) ``` ## الأعداد الكبيرة والزمن وFFI **البيانات والتشفير** - `ضخم` يستقبل الأعداد الصحيحة كنصوص ويعيد نصوصًا لتجنب فقد الدقة؛ تشمل عملياته الجمع والطرح والضرب والقسمة والباقي والقوة والمضروب والمقارنة والتطبيع. - `زمن` يوفر وقت Unix، ساعة رتيبة للمدد، النوم، تحويلات تاريخ، تنسيق strftime وتحليل التواريخ. الدالة `نوم` حاجبة؛ في الشيفرة غير المتزامنة يوصي README بـ`نم`. - `ffi` يفتح مكتبة ويربط دالة حسب توقيع مثل `d(d)`، ويدير ذاكرة ومؤشرات. يتطلب صلاحية `اصلي` وهو غير آمن بطبيعته. - قيود FFI الموثقة: x86-64 وAArch64 فقط؛ حتى 6 وسائط صحيحة و8 عشرية؛ لا float ولا varargs ولا callbacks. > التحميل الأصلي وFFI ينفذان شيفرة خارجية بحق العملية. لا تستخدمهما مع مكتبة غير موثوقة، وافهم صلاحية `اصلي` وحدود المنصة أولًا. ## مصادر الوحدة والتحقق **التحميل والاستخدام** تواقيع الوحدات أعلاه موجزة وليست بديلًا عن مرجع README أو الملفات المصدرية. لم تُشغّل أمثلة هذه الصفحة؛ راجع تعليمات التثبيت ثم استخدم `solan --check` عند تجربة صياغة جديدة. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - src/lib/natives_core.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/natives_core.inc - src/lib/http_ws.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/http_ws.inc - src/lib/tls_net.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/tls_net.inc - src/lib/json.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/json.inc - src/lib/regex.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/regex.inc - src/lib/sqlite.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/sqlite.inc - src/lib/flate.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/flate.inc - src/lib/zlib.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/zlib.inc - src/lib/hash.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/hash.inc - src/lib/bigint_time.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/bigint_time.inc - src/lib/ffi.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/ffi.inc - src/lib/timers.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/timers.inc - src/runtime/init.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/init.inc - src/vm/modules.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/modules.inc # Built-in Native Libraries — English ## What are native modules? **Loading and use** These modules are built into the Solan executable rather than downloaded as external packages. Programs import them with `استورد "name"`. README identifies `نظام`, `جيسون`, `شبكة`, `سوكت`, and `حلقة` as always available without an explicit import; import the other modules before use. | Modules | Area | | --- | --- | | `رياضيات`, `ضخم`, `عشوائي`, `زمن` | Math, arbitrary-size integers, randomness, and time. | | `نظام`, `ملفات`, `جيسون`, `نمط` | Environment/processes, files, JSON, and regular expressions. | | `تشفير`, `ضغط` | Hashes, HMAC, Base64/hex, gzip/zlib. | | `شبكة`, `سوكت`, `ويبسوكت`, `حلقة` | HTTP/TLS, TCP/UDP, WebSocket, event-loop handles and timers. | | `قاعدة`, `ffi` | SQLite and calling C libraries or loading native modules. | ## HTTP and web servers **Networking** | Function | Source-described behavior | | --- | --- | | `شبكة.جلب(url, options?)` | Blocking HTTP/HTTPS request returning a map with status, body, headers, success, and final URL. Options include method, headers, body, timeout, redirects, TLS verification, and form encodings. | | `شبكة.جلب_متدفق(url, callback, options?)` | Calls back with transport chunks before completion, then returns the usual response map. The call itself is synchronous/blocking. | | `شبكة.خادم(port, handler, options?)` | Blocking HTTP server; handler receives a request map. Returning text produces HTML; a map can specify status, headers, and body. | | `شبكة.خادم_حلقة(...)` | Event-loop HTTP server; supports an asynchronous handler. | | `شبكة.ترميز_رابط(text)` / `فك_رابط(text)` | URL component encoding and decoding. | | `شبكة.اقرا_طلب(...)` / `اكتب_رد(...)` | Lower-level HTTP handling over sockets. | > With `جلب_متدفق`, an SSE event or UTF-8 character may span chunks. Buffer and reassemble before parsing events or decoding text. A failure after partial data raises rather than returning a partial response as complete. > HTTPS and WSS require runtime OpenSSL in the configuration described by README; without TLS, ordinary HTTP/TCP still works. Do not disable certificate verification without a specific reason. ## TCP, UDP, WebSocket, and the event loop **Networking** - `سوكت` provides listen, accept, connect, send, bounded/exact/line reads, timeouts, nonblocking mode, readiness waits, DNS, UDP operations, and handle closure. - `ويبسوكت` connects to `ws://` or `wss://`, upgrades inbound HTTP, sends/receives messages and ping, and closes channels. - `حلقة` is a single-threaded event loop with one-shot/repeating timers, handle watchers, step/run/stop operations. **README-shaped calls (not rerun)** ```solan خل مقبض = سوكت.اتصل("localhost", 9000) سوكت.ارسل(مقبض, "مرحبا") خل م = حلقة.كل(1, دالة() { اطبع("tick") }) حلقة.الغ(م) ``` ## JSON, regex, SQLite, compression, and cryptography **Data and cryptography** | Module | Documented API and behavior | | --- | --- | | `جيسون` | `ترميز(value, spacing?)` encodes a value; `فك(text)` parses JSON and maps null to `عدم`. | | `نمط` | `ابحث`, `هل`, `مطابق_كامل`, `كل`, `قسم`, `ابدل`; supports named groups and case-insensitive, normalization, multiline, and dotall options. | | `قاعدة` | `افتح`, `نفذ`, `استعلم`, `اغلق`; SELECT returns a list of maps. Pass values separately in a list of `?` parameters rather than concatenating SQL text. | | `ضغط` | `gzip`, `gunzip`, `zlib`, `فك`; core compression is bundled and documented output limit is 512 MiB for decompression protection. | | `تشفير` | `sha256`, `sha1`, `hmac_sha256`, `base64`/`فك_base64`, `hex`/`فك_hex`, `عشوائي_بايتات`. | **SQLite pattern from README (not rerun)** ```solan استورد "قاعدة" خل ق = قاعدة.افتح("t.db") قاعدة.نفذ(ق, "INSERT INTO ت VALUES (?, ?)", [1, "س"]) خل صفوف = قاعدة.استعلم(ق, "SELECT * FROM ت WHERE ا = ?", [1]) قاعدة.اغلق(ق) ``` ## Big integers, time, and FFI **Data and cryptography** - `ضخم` accepts integer values as strings and returns strings to avoid precision loss; documented operations include add, subtract, multiply, integer divide, remainder, power, factorial, compare, and normalization. - `زمن` provides Unix time, a monotonic duration clock, sleep, date conversion, strftime formatting, and parsing. `نوم` blocks; README recommends `نم` in asynchronous code. - `ffi` opens a library, binds functions using signatures such as `d(d)`, and manages memory/pointers. It requires the `اصلي` permission and is inherently unsafe. - Documented FFI limits: x86-64 and AArch64 only; up to 6 integer and 8 floating-point arguments; no float ABI, varargs, or callbacks. > Native loading and FFI execute external code within the process. Do not use them with untrusted libraries; understand the `اصلي` permission and platform limits first. ## Module sources and verification **Loading and use** The signatures above are concise and do not replace the README or source files. Examples on this page were not executed; follow the install page, then use `solan --check` when testing new syntax. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - src/lib/natives_core.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/natives_core.inc - src/lib/http_ws.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/http_ws.inc - src/lib/tls_net.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/tls_net.inc - src/lib/json.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/json.inc - src/lib/regex.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/regex.inc - src/lib/sqlite.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/sqlite.inc - src/lib/flate.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/flate.inc - src/lib/zlib.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/zlib.inc - src/lib/hash.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/hash.inc - src/lib/bigint_time.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/bigint_time.inc - src/lib/ffi.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/ffi.inc - src/lib/timers.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/timers.inc - src/runtime/init.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/init.inc - src/vm/modules.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/modules.inc # سطر الأوامر وREPL وأوامر الحزم — العربية ## ملف، كود مباشر، وREPL **تشغيل البرنامج** | الأمر | الوظيفة | | --- | --- | | `solan ملف.سو [وسائط...]` | يشغّل ملفًا، والوسائط تصبح متاحة في المتغير العام `وسائط`. امتدادات README: `.سو` و`.an` و`.solan`. | | `solan -e "كود"` | يشغّل نصًا برمجيًا مباشرًا من الطرفية. | | `solan` | يفتح REPL؛ يعرض ناتج التعبير، ويكمل الإدخال متعدد الأسطر، ويستخدم التاريخ عند توفر readline. للخروج `خروج` أو `exit` أو Ctrl+D. | | `#!/usr/bin/env solan` | يمكن وضعه في بداية الملف لتشغيله كسكربت تنفيذي عند ضبط صلاحيات الملف. | **أمثلة أوامر من README (لم تُنفذ)** ```text solan ملف.سو solan -e 'اطبع(1 + 2)' solan ``` ## الفحص والتنسيق والتصحيح وخادم اللغة **أدوات التطوير** | الأمر | السلوك | | --- | --- | | `solan --check ملف.سو` | يفحص الصياغة دون تشغيل البرنامج؛ يطبع سليم أو رسالة الخطأ. | | `solan fmt ملف.سو [-w]` | ينسق الإزاحة والمسافات ونهايات الأسطر؛ `-w` يكتب التغيير إلى الملف وإلا يطبع النتيجة. | | `solan fmt ملف.سو --قياسي [-w]` | يحول مرادفات الكلمات المفتاحية إلى الصيغة القياسية. | | `solan --لون ملف.سو` / `--html` | تلوين الطرفية أو إنشاء HTML ملون. | | `solan --تتبع ملف.سو` | يطبع سطور التنفيذ أثناء التشغيل. | | `solan --تصحيح ملف.سو [--نقطة N]` | مصحح تفاعلي خطوة بخطوة مع نقطة توقف اختيارية. | | `solan --ops ملف.سو` | يعرض تعليمات bytecode الداخلية، للمطورين. | | `solan lsp` | يشغّل خادم لغة LSP عبر stdio؛ يدعم completion وhover وتعريفًا ورموز المستند وتشخيصات صياغة وفق ملف الخادم. | ## الصلاحيات والحدود والألوان **الخيارات العامة** | الخيار | الغرض | | --- | --- | | `--اسمح=فئة,...` / `--امنع=فئة,...` | يمنح أو يمنع فئات الصلاحية؛ تفاصيل الحدود في صفحة الأمان. | | `--اسمح-قراءة=مسار` / `--اسمح-كتابة=مسار` / `--اسمح-شبكة=مضيف` | يقيد ملفات القراءة/الكتابة أو مضيفي الشبكة. | | `--آمن` | وضع آمن يقتصر على القراءة والبيئة وفق README. | | `--حد_وقت N` / `--حد_ذاكرة N` | حد زمني بالثواني وحد ذاكرة بالميغابايت. | | `--بلا_لون` | يعطل ألوان الطرفية. | | مكافئات إنجليزية | `--trace`، `--debug`، `--safe`، `--allow`، `--deny`، `--timeout`، `--max-mem`، `--no-color`، `--break`، `--color`. | ## أوامر الحزم **مدير الحزم** | الأمر | الاستخدام الموثق | | --- | --- | | `solan init [--lib]` | إنشاء solan.json؛ و`--lib` ينشئ هيكل مكتبة. | | `solan add [اسم=]مصدر[@نطاق]` | إضافة وتثبيت اعتماد؛ `--as اسم` اسم بديل. | | `solan install [--local] [--quiet]` | تثبيت بيان المشروع، مع تفضيل المتجر المحلي اختياريًا. | | `solan install --frozen` | قفل دون ترقية، ويتحقق من بصمات المحتوى. | | `solan remove اسم...` / `solan update [اسم] [--major]` | حذف اعتماد أو تحديثه ضمن النطاق. | | `solan list [--tree] [--store]` | عرض الاعتمادات/شجرتها/المتجر. | | `solan outdated` / `why اسم` / `verify` | فحص الإصدارات، مصدر اعتماد، أو سلامة القفل. | | `solan prune [--dry-run]` / `cache clean` | تنظيف المتجر المشترك أو التنزيلات المؤقتة. | | `solan publish [--dry-run] [--push]` | فحص المكتبة وإنشاء وسم إصدار؛ `--push` يدفعه. | اسماء الأوامر العربية تشمل `ثبت` و`اضف` و`ازل` و`قائمة` و`حدث` و`تحقق` و`قديمة` و`لماذا` و`تنظيف` و`كاش` و`انشر` و`بدء`. انظر صفحة المكتبة القياسية لقيود القفل والتخزين. ## رموز الخروج وصفحة التثبيت **التشغيل** | الرمز | المعنى | | --- | --- | | `0` | نجاح. | | `65` | خطأ صياغة. | | `66` | تعذر فتح الملف. | | `70` | خطأ تشغيل غير ممسوك. | | `64` | خيار صلاحيات غير صالح. | > تعليمات تثبيت Linux/macOS/Windows ومتطلبات البناء موجودة في الصفحة الحالية `/install`؛ لم نكررها هنا حتى تبقى في مكان واحد. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - src/runtime/main.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/main.inc - src/runtime/repl.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/repl.inc - src/runtime/tools.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/tools.inc - src/lib/natives_core.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/natives_core.inc - stdlib/حزم.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AD%D8%B2%D9%85.%D8%B3%D9%88 # CLI, REPL, and Package Commands — English ## Files, inline code, and the REPL **Running programs** | Command | Behavior | | --- | --- | | `solan file.سو [args...]` | Runs a file; arguments are exposed in the global `وسائط`. README lists `.سو`, `.an`, and `.solan` extensions. | | `solan -e "code"` | Executes inline source from the terminal. | | `solan` | Starts the REPL; prints expression results, supports multiline input, and uses history when readline is available. Exit with `خروج`, `exit`, or Ctrl+D. | | `#!/usr/bin/env solan` | May appear at the start of a file to run it as a script when executable permissions are set. | **README command shapes (not executed)** ```text solan file.سو solan -e 'اطبع(1 + 2)' solan ``` ## Checks, formatting, debugging, and language server **Developer tools** | Command | Behavior | | --- | --- | | `solan --check file.سو` | Checks syntax without running; prints success or an error. | | `solan fmt file.سو [-w]` | Formats indentation, whitespace, and blank lines; `-w` writes to the file, otherwise prints output. | | `solan fmt file.سو --قياسي [-w]` | Normalizes keyword aliases to canonical keywords. | | `solan --لون file.سو` / `--html` | Syntax colors in terminal or generated HTML. | | `solan --تتبع file.سو` | Prints executed source lines. | | `solan --تصحيح file.سو [--نقطة N]` | Interactive step-by-step debugger with an optional breakpoint. | | `solan --ops file.سو` | Displays internal bytecode instructions for developers. | | `solan lsp` | Starts the stdio LSP server; source advertises completion, hover, definition, document symbols, and syntax diagnostics. | ## Permissions, limits, and colors **Global options** | Option | Purpose | | --- | --- | | `--اسمح=class,...` / `--امنع=class,...` | Grants or denies permission classes; see the security page for scope details. | | `--اسمح-قراءة=path` / `--اسمح-كتابة=path` / `--اسمح-شبكة=host` | Scopes file read/write or network access. | | `--آمن` | Safe mode; README describes it as read and environment only. | | `--حد_وقت N` / `--حد_ذاكرة N` | Time limit in seconds and memory limit in MiB. | | `--بلا_لون` | Disables terminal colors. | | English aliases | `--trace`, `--debug`, `--safe`, `--allow`, `--deny`, `--timeout`, `--max-mem`, `--no-color`, `--break`, `--color`. | ## Package commands **Package manager** | Command | Documented use | | --- | --- | | `solan init [--lib]` | Creates solan.json; `--lib` creates a library scaffold. | | `solan add [name=]source[@range]` | Adds and installs a dependency; `--as name` is an alternative naming form. | | `solan install [--local] [--quiet]` | Installs project manifest dependencies; optionally prefers local store. | | `solan install --frozen` | Uses the lock without upgrades and checks content hashes. | | `solan remove name...` / `solan update [name] [--major]` | Removes or updates dependencies within ranges. | | `solan list [--tree] [--store]` | Lists dependencies, their tree, or the package store. | | `solan outdated` / `why name` / `verify` | Checks versions, dependency provenance, or lock integrity. | | `solan prune [--dry-run]` / `cache clean` | Cleans unused shared-store packages or temporary downloads. | | `solan publish [--dry-run] [--push]` | Checks a library and creates a release tag; `--push` pushes it. | Arabic command names include `ثبت`, `اضف`, `ازل`, `قائمة`, `حدث`, `تحقق`, `قديمة`, `لماذا`, `تنظيف`, `كاش`, `انشر`, and `بدء`. See the standard-library page for lock/store constraints. ## Exit codes and installation page **Execution** | Code | Meaning | | --- | --- | | `0` | Success. | | `65` | Syntax error. | | `66` | Could not open file. | | `70` | Uncaught runtime error. | | `64` | Invalid permission option. | > Current Linux/macOS/Windows installation instructions and build prerequisites remain at `/install`; they are intentionally not duplicated here. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - src/runtime/main.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/main.inc - src/runtime/repl.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/repl.inc - src/runtime/tools.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/tools.inc - src/lib/natives_core.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/natives_core.inc - stdlib/حزم.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AD%D8%B2%D9%85.%D8%B3%D9%88 # واجهة C والامتدادات الأصلية — العربية ## بناء وحدة C وربطها **وحدة C أصلية** تعرّف الوحدة الأصلية دالة C بتوقيع callback موحد، ثم تصدّر نقطة الدخول `solan_module_init(SolanModule *m)`. تستخدم `solan_module_add_function` لتسجيل الدوال و`solan_module_add_value` لتسجيل قيمة. **هيكل callback كما في README — لم يُبنَ في هذه المهمة** ```solan #include "solan.h" static int add(int argc, const SolanValue *argv, SolanValue *res, void *user) { (void)user; (void)argc; if (!solan_is_number(argv[0]) || !solan_is_number(argv[1])) return solan_throw("جمع: يتطلب رقمين"); *res = solan_number(solan_to_number(argv[0]) + solan_to_number(argv[1])); return 0; } int solan_module_init(SolanModule *m) { solan_module_add_function(m, "جمع", add, 2, 2, NULL); solan_module_add_value(m, "الاصدار", solan_number(1)); return 0; } ``` - ابنِ الوحدة كملف shared object مع `-fPIC -shared` ومرر `-I include`؛ في المثال الملف الناتج `hello.so`. - تُستورد الوحدة من Solan بمسار نسبي إلى الملف؛ اسمها في البرنامج مشتق من اسم الملف دون الامتداد. - ملف Solan التنفيذي يصدّر رموز `solan_*` بعلم الربط الديناميكي المناسب؛ لا تربط الامتداد بـ`libsolan` أو بالملف التنفيذي وفق README. ## القيم والوظائف العامة **الأنواع والقيم** | المجموعة | أسماء API التي يذكرها README | | --- | --- | | إنشاء قيم | `solan_nil`، `solan_bool`، `solan_number`، `solan_string`، `solan_list_new`، `solan_map_new`. | | الفحص والتحويل | `solan_is_*`، `solan_to_bool`، `solan_to_number`، `solan_to_cstr`. | | القوائم والقواميس | `solan_list_len/get/push`، `solan_map_set/get`. | | الأخطاء والجذور | `solan_throw`، `solan_pin`، `solan_unpin` لحماية القيم من جامع المهملات. | | تضمين المفسر | `solan_init`، `solan_register_function`، `solan_eval`، `solan_call`، `solan_last_error`، `solan_eval_file`، `solan_abi_version`. | > هذه قائمة أسماء موثقة مختصرة، وليست بديلًا عن تعريفات الأنواع والتواقيع في `include/solan.h`. راجع الرأس مباشرة للوسائط وأنواع الإرجاع وعمر القيم. ## تضمين مفسر Solan في برنامج C **تضمين** يُبنى المشروع كـshared library عند استخدام `-DSOLAN_LIBRARY`، ثم يستدعي برنامج C `solan_init()`، ويسجل دالة أصلية إن احتاج، ويمرر مصدرًا إلى `solan_eval`، أو يستدعي دالة Solan موجودة بواسطة `solan_call`. توثّق الأمثلة `solan_last_error()` لقراءة الخطأ. **نمط ترجمة مذكور في README — لم يُشغّل** ```text cc -O2 -fPIC -shared -DSOLAN_LIBRARY -Wno-format-truncation -o libsolan.so solan.c -lm -ldl cc -I include -o demo demo.c -L. -lsolan -Wl,-rpath,. ``` ## FFI والقيود والصلاحيات **الأمان والمنصة** - استدعاء `ffi` المباشر يربط اسم دالة C بتوقيع مثل `d(d)`؛ رموز الأنواع تشمل `i` و`l` و`p` و`d` و`s` و`b` و`v` وفق README. - يدعم FFI x86-64 وAArch64 فقط، وحتى 6 وسائط صحيحة و8 عشرية؛ لا يدعم float أو variadic calls أو callbacks. - تحميل `ffi` والوحدات الأصلية يتطلب صلاحية `اصلي`، وهي صلاحية غير آمنة بطبيعتها. تقييدها حسب سياسة التشغيل قبل تنفيذ كود طرف ثالث. > الأمثلة هنا مقتبسة أو مُلخّصة من README ولم تُبنَ أو تُشغّل ضمن هذه المهمة. ABI يتأثر بالمنصة والمترجم؛ لا تستخدم هذا المرجع وحده لاستنتاج ملكية الذاكرة أو التوافق الثنائي. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - include/solan.h — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/include/solan.h - src/abi/capi.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/abi/capi.inc - src/runtime/init.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/init.inc - src/lib/ffi.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/ffi.inc - src/platform/platform.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/platform/platform.inc # C API and Native Extensions — English ## Building and binding a C module **Native C module** A native module defines C callbacks with the shared function signature and exports `solan_module_init(SolanModule *m)`. Register functions with `solan_module_add_function` and values with `solan_module_add_value`. **README callback shape — not built in this task** ```solan #include "solan.h" static int add(int argc, const SolanValue *argv, SolanValue *res, void *user) { (void)user; (void)argc; if (!solan_is_number(argv[0]) || !solan_is_number(argv[1])) return solan_throw("جمع: يتطلب رقمين"); *res = solan_number(solan_to_number(argv[0]) + solan_to_number(argv[1])); return 0; } int solan_module_init(SolanModule *m) { solan_module_add_function(m, "جمع", add, 2, 2, NULL); solan_module_add_value(m, "الاصدار", solan_number(1)); return 0; } ``` - Build a shared object with `-fPIC -shared` and `-I include`; the README example outputs `hello.so`. - Import the module from Solan using a relative path; the module name is derived from the filename without extension. - The executable exports `solan_*` symbols with the appropriate dynamic-linker flag; README says not to link the extension against `libsolan` or the executable. ## Values and public API **Values and API** | Group | API names documented in README | | --- | --- | | Value construction | `solan_nil`, `solan_bool`, `solan_number`, `solan_string`, `solan_list_new`, `solan_map_new`. | | Checks and conversion | `solan_is_*`, `solan_to_bool`, `solan_to_number`, `solan_to_cstr`. | | Lists and maps | `solan_list_len/get/push`, `solan_map_set/get`. | | Errors and GC roots | `solan_throw`, `solan_pin`, `solan_unpin` to keep values rooted from garbage collection. | | Embedding | `solan_init`, `solan_register_function`, `solan_eval`, `solan_call`, `solan_last_error`, `solan_eval_file`, `solan_abi_version`. | > This is a concise name index, not a substitute for type definitions and signatures in `include/solan.h`. Check the header for arguments, return types, and value lifetimes. ## Embedding Solan in a C program **Embedding** Build as a shared library with `-DSOLAN_LIBRARY`, then call `solan_init()` from C, optionally register a native function, pass source to `solan_eval`, or invoke a Solan function with `solan_call`. README examples use `solan_last_error()` to read failures. **README build patterns — not run** ```text cc -O2 -fPIC -shared -DSOLAN_LIBRARY -Wno-format-truncation -o libsolan.so solan.c -lm -ldl cc -I include -o demo demo.c -L. -lsolan -Wl,-rpath,. ``` ## FFI, constraints, and permissions **Security and platform** - Direct `ffi` binding associates a C symbol with a signature such as `d(d)`; README lists type codes `i`, `l`, `p`, `d`, `s`, `b`, and `v`. - FFI supports x86-64 and AArch64, up to 6 integer and 8 floating-point arguments; no float, varargs, or callbacks. - Direct FFI and native-module loading require the `اصلي` permission, which is inherently unsafe. Apply runtime permission policy before executing third-party native code. > Examples are quoted or summarized from README and were not compiled or run in this task. ABI behavior varies by platform/compiler; do not infer ownership or binary compatibility from this page alone. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - include/solan.h — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/include/solan.h - src/abi/capi.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/abi/capi.inc - src/runtime/init.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/init.inc - src/lib/ffi.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/ffi.inc - src/platform/platform.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/platform/platform.inc # معمارية المترجم ووقت التشغيل — العربية ## من النص إلى التنفيذ **مسار التنفيذ** يصف README المشروع كملف C رئيسي واحد (`solan.c`) يضم ملفات `.inc` في وحدة ترجمة واحدة. تتولى ملفات compiler تحليل الشيفرة وتحويلها إلى bytecode؛ وتنفّذ VM التعليمات وإدارة القيم والطرق والوحدات. يوجد مسار JIT اختياري لـx86-64، وليس شرطًا لعمل المفسر. | المكوّن | المسؤولية حسب شجرة المصدر | | --- | --- | | `src/compiler/` | الماسح المعجمي، compiler إلى bytecode، فك التعليمات، وتلوين الشيفرة. | | `src/vm/` | الآلة الافتراضية وطرق الأنواع والوحدات. | | `src/core/` | الأنواع وجامع المهملات والذاكرة وتحويل القيم إلى نص. | | `src/jit/` | المجمّع الفوري لـx86-64؛ يفعّل افتراضيًا على Linux x86-64 وفق README ويمكن تعطيله. | | `src/runtime/` | نقطة التشغيل وREPL وأدوات fmt/LSP وتهيئة الدوال المدمجة. | | `src/lib/` | المكتبات الأصلية: ملفات، شبكات، JSON، regex، ضغط، SQLite، TLS، FFI، حزم، زمن، وأعداد ضخمة. | | `src/abi/` | واجهة C في `capi.inc` ورأس `include/solan.h`. | | `src/platform/` | فروق المنصات POSIX وWindows. | | `stdlib/` و`editor/vscode/` | مكتبات قياسية مكتوبة بسولان وإضافة VS Code. | ## الخصائص التي تعتمد على إعداد البناء **البناء والخصائص** - الـJIT يستخدم `src/jit/`؛ README يذكر أنه يعمل افتراضيًا على Linux x86-64 فقط، ويمكن إيقافه بالبناء مع `-DSOLAN_JIT=0` أو بمتغير وقت التشغيل `SOLAN_JIT=0`. - يمكن تضمين SQLite عند البناء إذا توفرت ملفاتها؛ وإلا تحاول اللغة تحميل `libsqlite3` من النظام عند تشغيل المكتبة. - الضغط gzip/zlib مضمّن. OpenSSL يُحمّل ديناميكيًا لـHTTPS/WSS وخادم TLS؛ عدم توفره لا يمنع HTTP/TCP غير المشفر. - يتطلب البناء مترجم C؛ `git` مطلوب لأوامر إدارة الحزم التي تتصل بالمستودعات، وليس لتشغيل ملف Solan موجود. > هذه حقائق من README وشجرة المصدر، وليست قياسات أداء أو وصفًا لكل تحسين داخلي. لا نستنتج عتبات JIT أو أداء نسبيًا لم يُذكر في الملفات المرتبطة. ## تحديث مكتبة stdlib المضمنة **التطوير** ملفات `stdlib/*.سو` هي المصدر المقروء للوحدات القياسية. يصف README إعادة توليد النسخة المضمّنة ثم البناء عبر `install.sh --build-only` بعد تعديل مكتبة قياسية. انظر صفحة المكتبة القياسية لفهرس الوحدات وروابطها. **أمر البناء المذكور في README (لم يُشغّل)** ```text sh install.sh --build-only ``` ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - solan.c — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/solan.c - src/compiler/lexer.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/lexer.inc - src/compiler/compiler.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/compiler.inc - src/compiler/opcodes.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/opcodes.inc - src/vm/vm_core.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/vm_core.inc - src/vm/vm_run.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/vm_run.inc - src/vm/methods.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/methods.inc - src/core/types.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/core/types.inc - src/core/gc.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/core/gc.inc - src/core/memory.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/core/memory.inc - src/jit/jit.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/jit/jit.inc - src/jit/x64.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/jit/x64.inc - src/runtime/main.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/main.inc - src/runtime/repl.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/repl.inc - src/runtime/tools.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/tools.inc - src/platform/platform.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/platform/platform.inc # Compiler and Runtime Architecture — English ## From source text to execution **Execution pipeline** README describes one C entry file (`solan.c`) that includes `.inc` files into a single translation unit. Compiler files parse source and emit bytecode; the VM executes instructions and manages values, methods, and modules. An optional x86-64 JIT exists but is not required for interpreter operation. | Component | Responsibility in the source tree | | --- | --- | | `src/compiler/` | Lexer, bytecode compiler, disassembler, syntax highlighting. | | `src/vm/` | Virtual machine, value methods, and modules. | | `src/core/` | Types, garbage collector, memory, and value-to-text conversion. | | `src/jit/` | x86-64 JIT; enabled by default on Linux x86-64 per README and can be disabled. | | `src/runtime/` | Runtime entry, REPL, fmt/LSP tools, built-in initialization. | | `src/lib/` | Native libraries: files, network, JSON, regex, compression, SQLite, TLS, FFI, packages, time, and big integers. | | `src/abi/` | C interface in `capi.inc` and public header `include/solan.h`. | | `src/platform/` | POSIX and Windows differences. | | `stdlib/` and `editor/vscode/` | Solan-written standard modules and the VS Code extension. | ## Build-dependent features **Build and features** - The JIT lives in `src/jit/`; README says it is enabled by default only on Linux x86-64 and can be disabled with `-DSOLAN_JIT=0` at build time or `SOLAN_JIT=0` at runtime. - SQLite can be embedded when its source files are available; otherwise Solan attempts to load system `libsqlite3` when the module is used. - gzip/zlib compression is bundled. OpenSSL is dynamically loaded for HTTPS/WSS/TLS servers; its absence does not prevent unencrypted HTTP/TCP. - A C compiler is required to build. `git` is needed for package commands that access repositories, not for running an existing Solan executable. > These are README/source-tree facts, not performance measurements or a complete account of every optimization. No JIT thresholds or comparative performance are inferred here. ## Updating the embedded standard library **Development** `stdlib/*.سو` are the readable sources of standard modules. README says to regenerate the embedded copy and build with `install.sh --build-only` after changing a standard module. See the standard-library page for the module index and links. **README build command (not run)** ```text sh install.sh --build-only ``` ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - solan.c — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/solan.c - src/compiler/lexer.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/lexer.inc - src/compiler/compiler.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/compiler.inc - src/compiler/opcodes.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/opcodes.inc - src/vm/vm_core.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/vm_core.inc - src/vm/vm_run.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/vm_run.inc - src/vm/methods.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/methods.inc - src/core/types.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/core/types.inc - src/core/gc.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/core/gc.inc - src/core/memory.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/core/memory.inc - src/jit/jit.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/jit/jit.inc - src/jit/x64.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/jit/x64.inc - src/runtime/main.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/main.inc - src/runtime/repl.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/repl.inc - src/runtime/tools.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/tools.inc - src/platform/platform.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/platform/platform.inc # الأمان والصلاحيات وحدود الثقة — العربية ## الصلاحيات الافتراضية والفئات **وقت التشغيل** وفق README، يملك البرنامج افتراضيًا كل الصلاحيات. يمكن تقييدها بست فئات: `قراءة` و`كتابة` و`شبكة` و`تنفيذ` و`بيئة` و`اصلي`، ويجمع `الكل` الفئات. الخيار `--اسمح=فئات` يمنح ما سُمي ويمنع ما عداه؛ `--امنع=فئات` يسحب فئات من المجموعة المسموحة. | مثال | الأثر الموثق | | --- | --- | | `--اسمح=قراءة` | يسمح بالقراءة ويمنع الفئات الأخرى. | | `--امنع=تنفيذ,شبكة` | يسمح افتراضيًا ثم يسحب التنفيذ والشبكة. | | `--اسمح-قراءة=/بيانات` / `--اسمح-كتابة=/مخرجات` | يحصر قراءة/كتابة الملفات في المسارات المحددة؛ الفحص بعد حل الروابط الرمزية و`..`. | | `--اسمح-شبكة=example.com` | يحصر الشبكة بالمضيف المطابق أو نطاق فرعي منه. | | `--آمن` أو `SOLAN_SAFE=1` | وضع آمن لقراءة الملفات والبيئة فقط وفق README. | **أمثلة خيارات من README (لم تُشغّل)** ```text solan --اسمح-قراءة=/بيانات --اسمح-كتابة=/مخرجات --اسمح-شبكة=api.example.com سكربت.سو solan --امنع=تنفيذ,شبكة سكربت.سو solan --آمن سكربت.سو ``` ## قيود الحزم والتحقق من سلامتها **سلسلة الإمداد** | الضابط | الحد أو السلوك في README | | --- | --- | | تنفيذ الشيفرة أثناء التثبيت | لا تنفّذ سكربتات المكتبة وقت التثبيت أو النشر. | | الروابط الرمزية | ممنوعة داخل مكتبة منشورة أو مثبتة. | | الحجم والعدد | حتى 5000 ملف و50 MiB للحزمة. | | الاعتماديات | عمق حتى 16 ومستودع حتى 500 حزمة. | | مصادر Git | https/http/ssh/git/file فقط؛ `ext::` مرفوض. | | القفل | يسجل commit وSHA-256؛ `install --frozen` و`verify` يعيدان التحقق. لا يوجد توقيع رقمي حسب README. | > الالتزام والبصمة يكشفان تغير محتوى عن lockfile؛ لا يثبتان وحدهما أن الناشر أو المصدر موثوق، ولا يعادلان توقيعًا رقميًا. ## ليس صندوق رمل كاملًا **حدود الثقة** - README ينبه صراحةً أن وضع safe والصلاحيات ليست sandbox كاملة لنظام التشغيل. تعامل معها كقيود داخل Solan لا كعزل للعملية أو حماية من كل ثغرات النظام. - الوحدات الأصلية وFFI تتطلب فئة `اصلي` لكنها تستدعي كود C داخل العملية؛ لا تمنحها لكود غير موثوق. - افتراضية منح كل الصلاحيات تجعل تشغيل كود غير موثوق غير آمن ما لم تفرض سياسة أقل صلاحية عبر الخيارات. - في HTTPS/WSS ينبغي إبقاء التحقق من TLS مفعّلًا؛ خيار تعطيله لا يحل مشكلة الثقة بل يضعفها. لإبلاغ الثغرات اتبع قناة SECURITY.md الرسمية للمشروع؛ هذه الصفحة مرجع هندسي وليست تقييمًا أمنيًا مستقلًا أو ضمانًا للسلامة. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - SECURITY.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/SECURITY.md - src/runtime/main.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/main.inc - src/lib/natives_core.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/natives_core.inc - src/lib/pkgs.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/pkgs.inc - stdlib/حزم.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AD%D8%B2%D9%85.%D8%B3%D9%88 - src/lib/ffi.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/ffi.inc # Security, Permissions, and Trust Boundaries — English ## Default permissions and classes **Runtime permissions** README states programs have all permissions by default. Six classes can be restricted: read, write, network, execute, environment, and native; `الكل` groups them. `--اسمح=classes` grants the named classes and denies the rest; `--امنع=classes` withdraws named permissions. | Example | Documented effect | | --- | --- | | `--اسمح=قراءة` | Allows read and denies the other classes. | | `--امنع=تنفيذ,شبكة` | Starts with permissions allowed, then withdraws execute and network. | | `--اسمح-قراءة=/data` / `--اسمح-كتابة=/output` | Scopes file access to paths, checked after resolving symlinks and `..`. | | `--اسمح-شبكة=example.com` | Scopes network access to the exact host or a subdomain. | | `--آمن` or `SOLAN_SAFE=1` | Safe mode is documented as read and environment only. | **README option examples (not run)** ```text solan --اسمح-قراءة=/بيانات --اسمح-كتابة=/مخرجات --اسمح-شبكة=api.example.com script.سو solan --امنع=تنفيذ,شبكة script.سو solan --آمن script.سو ``` ## Package constraints and integrity **Supply chain** | Control | README limit or behavior | | --- | --- | | Code execution during install | Library scripts are not executed during installation or publication. | | Symbolic links | Forbidden in installed/published libraries. | | Size and count | Up to 5,000 files and 50 MiB per package. | | Dependencies | Depth up to 16 and up to 500 packages. | | Git sources | Only https/http/ssh/git/file; `ext::` is rejected. | | Lockfile | Records commit and SHA-256; `install --frozen` and `verify` check integrity. README says there is no digital signature. | > A locked commit/hash detects content changes relative to the lockfile; it does not by itself prove publisher identity or replace a digital signature. ## Not a full sandbox **Trust limits** - README explicitly warns that safe mode and permissions are not a full operating-system sandbox. Treat them as Solan-level restrictions, not process isolation or protection from every OS vulnerability. - Native modules and FFI require `اصلي` but execute C code in-process; do not grant it to untrusted code. - Because all permissions are granted by default, running untrusted programs is unsafe unless a least-privilege policy is applied. - Keep TLS verification enabled for HTTPS/WSS; disabling it weakens trust rather than fixing it. Use the project’s SECURITY.md reporting channel for vulnerability reports. This page is an engineering reference, not an independent audit or safety guarantee. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - SECURITY.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/SECURITY.md - src/runtime/main.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/main.inc - src/lib/natives_core.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/natives_core.inc - src/lib/pkgs.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/pkgs.inc - stdlib/حزم.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AD%D8%B2%D9%85.%D8%B3%D9%88 - src/lib/ffi.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/lib/ffi.inc # المنصات والاعتماديات — العربية ## الأنظمة المذكورة في المصدر **الأهداف** | النظام | المعلومة المصدرية | | --- | --- | | Linux | ضمن أهداف install.sh؛ JIT مفعّل افتراضيًا فقط على Linux x86-64 وفق README. | | macOS وBSD | مذكوران ضمن طريقة البناء السريعة وأعلام الربط الخاصة بالمنصة. | | Windows | هدف install.sh؛ README يشرح مسار MSYS2 UCRT64 أو PowerShell وملف install.ps1، ويذكر DLL لـOpenSSL بجوار الملف التنفيذي للـHTTPS. | | Android | مذكور كهدف بناء عابر عبر `--target android` و`CC`؛ لا نعد هنا بتوافر كل الخصائص على كل جهاز Android. | > صفحة `/install` الحالية تظل المرجع الوحيد لخطوات التثبيت الدقيقة؛ هذه الصفحة تصف الأهداف والاعتماديات فقط. ## ما يحتاجه البناء والتشغيل **الاعتماديات** | المكوّن | متى يلزم | | --- | --- | | مترجم C (gcc أو clang) | للبناء فقط؛ README لا يشترط make. | | OpenSSL 3 / libssl | لـHTTPS وWSS فقط؛ يُحمّل وقت التشغيل إن توفر. HTTP/TCP العاديان يعملان بدونه. | | git 2.x | لأوامر الحزم المتصلة بالمستودعات مثل add/install/update/publish؛ تشغيل البرامج المثبتة لا يحتاجه. | | SQLite | مضمّنة إذا توفرت ملفات المصدر وقت البناء، وإلا تستخدم libsqlite3 من النظام وقت التشغيل. | | JIT | ميزة اختيارية؛ البناء بلا JIT ممكن باستخدام `-DSOLAN_JIT=0`. | قد تختلف الأعلام ومكتبات الربط حسب المنصة. رابط التثبيت في أعلى/أسفل الموقع يتضمن خطوات إعداد المتطلبات واستخدام `install.sh` أو `install.ps1`. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - install.sh — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/install.sh - install.ps1 — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/install.ps1 - src/platform/platform.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/platform/platform.inc - src/jit/jit.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/jit/jit.inc - src/jit/x64.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/jit/x64.inc # Platforms and Runtime Dependencies — English ## Targets named by the source **Targets** | Platform | Source information | | --- | --- | | Linux | An install.sh target; README says the JIT is enabled by default only on Linux x86-64. | | macOS and BSD | Listed in the quick-build targets and platform-specific linker flags. | | Windows | An install.sh target; README describes MSYS2 UCRT64 or PowerShell/install.ps1 and placing the OpenSSL DLL beside the executable for HTTPS. | | Android | Listed as a cross-build target using `--target android` and `CC`; this page does not promise all features on every Android device. | > The existing `/install` page remains the single source for exact installation steps; this page only summarizes targets and dependencies. ## Build and runtime requirements **Dependencies** | Component | When required | | --- | --- | | C compiler (gcc or clang) | Build only; README does not require make. | | OpenSSL 3 / libssl | HTTPS and WSS only; loaded at runtime when available. Plain HTTP/TCP works without it. | | git 2.x | Repository-backed package commands such as add/install/update/publish; running installed programs does not need it. | | SQLite | Embedded when source files are available during build; otherwise system libsqlite3 is used at runtime. | | JIT | Optional; builds can disable it with `-DSOLAN_JIT=0`. | Flags and linked libraries vary by platform. The existing install page includes prerequisite setup and `install.sh`/`install.ps1` instructions. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - install.sh — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/install.sh - install.ps1 — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/install.ps1 - src/platform/platform.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/platform/platform.inc - src/jit/jit.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/jit/jit.inc - src/jit/x64.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/jit/x64.inc # VS Code وLSP وأدوات المحرر — العربية ## ما الذي توفره الإضافة؟ **المزايا** - قواعد تلوين لغوي عبر TextMate grammar. - قصاصات snippets وأقواس تلقائية وتعريف تعليقات `//` و`/* ... */` عبر ملف إعداد اللغة. - عميل LSP يطلق `solan lsp` ويستعمل قناة stdio؛ يدعم الخادم مزامنة المستندات والتشخيص والإكمال وhover والتعريف ورموز المستند وفق القدرات المعلنة. - README يذكر تفعيل الملفات ذات الامتدادات `.سو` و`.an` و`.solan`. > إذا لم يكن `solan` في PATH، يتيح إعداد VS Code `solan.path` تحديد المسار الكامل للملف التنفيذي. ## طريقة الإعداد ومصادر الإضافة **الإعداد** وفق README، مجلد `editor/vscode/` هو مصدر الإضافة. طريقة README اليدوية: نسخ المجلد إلى مجلد extensions المحلي باسم `solan-lang`، تثبيت الاعتماد `vscode-languageclient` باستخدام npm داخل المجلد، ثم إعادة تشغيل VS Code. لم تُنفّذ خطوات التثبيت في هذه المهمة. | الملف | الغرض | | --- | --- | | `package.json` | تعريف الإضافة واعتمادياتها وأوامر تشغيل العميل. | | `extension.js` | تشغيل عميل LSP وربطه بمفسر Solan. | | `language-configuration.json` | الأقواس والتعليقات وقواعد المحرر. | | `snippets/solan.json` | قصاصات إدخال للكود. | | `syntaxes/solan.tmLanguage.json` | قواعد تلوين الرموز. | > README يصرّح بأن الإضافة لم تُختبر داخل VS Code نفسه في بيئة التطوير؛ اعتبر دعم المحرر موثقًا من المصدر لا نتيجة اختبار قبول حديث. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - editor/vscode/package.json — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/editor/vscode/package.json - editor/vscode/extension.js — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/editor/vscode/extension.js - editor/vscode/language-configuration.json — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/editor/vscode/language-configuration.json - editor/vscode/snippets/solan.json — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/editor/vscode/snippets/solan.json - editor/vscode/syntaxes/solan.tmLanguage.json — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/editor/vscode/syntaxes/solan.tmLanguage.json - stdlib/خادم_اللغة.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AE%D8%A7%D8%AF%D9%85_%D8%A7%D9%84%D9%84%D8%BA%D8%A9.%D8%B3%D9%88 - src/runtime/tools.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/tools.inc # VS Code, LSP, and Editor Tools — English ## What the extension provides **Features** - TextMate grammar for syntax highlighting. - Snippets, auto-closing brackets, and `//` / `/* ... */` comment definitions through the language-configuration file. - An LSP client that launches `solan lsp` over stdio; the server advertises document sync, diagnostics, completion, hover, definition, and document symbols. - README lists `.سو`, `.an`, and `.solan` file extensions. > If `solan` is not on PATH, the VS Code setting `solan.path` accepts the executable path. ## Setup and extension sources **Setup** README identifies `editor/vscode/` as the extension source. Its manual method is to copy the folder into the local extensions directory as `solan-lang`, install `vscode-languageclient` with npm inside it, then restart VS Code. These installation steps were not performed in this task. | File | Purpose | | --- | --- | | `package.json` | Extension manifest, dependencies, and client activation. | | `extension.js` | Starts the LSP client and connects it to the Solan executable. | | `language-configuration.json` | Brackets, comments, and editor behavior. | | `snippets/solan.json` | Code snippets. | | `syntaxes/solan.tmLanguage.json` | Token-coloring grammar. | > README states that the extension was not tested inside VS Code in its development environment; treat this as source-documented support, not a fresh acceptance test. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - editor/vscode/package.json — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/editor/vscode/package.json - editor/vscode/extension.js — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/editor/vscode/extension.js - editor/vscode/language-configuration.json — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/editor/vscode/language-configuration.json - editor/vscode/snippets/solan.json — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/editor/vscode/snippets/solan.json - editor/vscode/syntaxes/solan.tmLanguage.json — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/editor/vscode/syntaxes/solan.tmLanguage.json - stdlib/خادم_اللغة.سو — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/stdlib/%D8%AE%D8%A7%D8%AF%D9%85_%D8%A7%D9%84%D9%84%D8%BA%D8%A9.%D8%B3%D9%88 - src/runtime/tools.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/tools.inc # مرجع Solan للذكاء الاصطناعي — العربية ## ملفات ونقاط دخول عامة **الوصول الآلي** | المورد | الاستخدام | | --- | --- | | /llms.txt | فهرس قصير لأقسام التوثيق والمصادر الأساسية. | | /llms-full.txt | نسخة نصية مجمعة ثنائية اللغة من دليل الموقع وصفحات المرجع ومصادرها. | | /sitemap.xml | المسارات العامة القابلة للفهرسة، بما فيها صفحات التوثيق. | | /robots.txt | سياسة الزحف العامة للموقع؛ صفحات التوثيق مسموحة، و`/api/` مستثنى. | | /solan-repository-index.json | قائمة JSON بملفات المستودع العام وروابطها في لقطة المصدر. | | GitHub | المصدر الأصلي للغة؛ عند التعارض، افحص الملف المربوط بدل افتراض أن النص المجمّع أحدث. | > هذه الروابط تجعل المحتوى قابلًا للقراءة والربط؛ لا تضمن أن كل مزود AI سيزحف إليه أو يفهرسه تلقائيًا. ## قواعد مقترحة لأي مساعد يكتب سولان **كتابة الكود** - اعتبر Solan لغة مستقلة؛ لا تحوّل تلقائيًا صياغة Python/JavaScript إلى مفردات إنجليزية إذا كان lexer يقبل الكلمات العربية. - تحقق من اسم الدالة وتوقيعها ونوع المستقبل في الصفحة المناسبة أو ملف المصدر. اسم الطريقة في mids لا يعني أنها موجودة لكل نوع. - ابدأ بالأمثلة التي يحدد المصدر أنها من README، لكن تحقق منها بإصدار المستخدم. المقتطفات التي وُسمت «غير مشغّلة» ليست اختبار تنفيذ. - لا تخترع واجهات تصدير أو أنواع معاملات/إرجاع حين لا يصرح بها الملف. اذكر ما بقي غير مؤكد. - لا تنسخ تعليمات التثبيت من هذا المرجع؛ وجّه المستخدم إلى `/install`، واستخدم `/docs/cli` لأوامر التشغيل. - للملفات المتغيرة بين الإصدارات، اربط إلى commit محدد أو افحص GitHub الحالي واذكر تاريخ الفحص. ## تعليمات جاهزة للنسخ إلى مساعد AI **قالب استعمال** **تعليمات عربية** ```text أنت تكتب بلغة Solan (سولان)، وهي لغة برمجة عربية. اقرأ https://solovip.me/llms.txt ثم الأقسام ذات الصلة في https://solovip.me/llms-full.txt. عند كتابة كود: استخدم أسماء الكلمات والطرق كما في التوثيق؛ تحقق من نوع المستقبل وتوقيع API في ملف المصدر المرتبط؛ لا تخترع دوالًا أو أنواع إرجاع؛ وعلّم أي مثال لم يُختبر على أنه غير مُشغّل. عندما لا تكفي الأدلة، قل ذلك بدل التخمين. تعليمات التثبيت: https://solovip.me/install ``` **English instructions** ```text You are writing Solan (سولان), an Arabic programming language. Read https://solovip.me/llms.txt, then the relevant sections in https://solovip.me/llms-full.txt. Use documented keyword and method spellings; verify receiver type and API signatures in linked source files; do not invent functions or return types; label untested examples as untested. If evidence is insufficient, say so instead of guessing. Installation: https://solovip.me/install ``` ## الفهرسة لا تعني اعتمادًا تلقائيًا **حدود المرجع** ملفات llms والصفحات المنظمة تساعد محركات البحث وأدوات AI التي تزحف إلى الموقع، لكنها لا تضيف الموقع تلقائيًا إلى بيانات تدريب نموذج، ولا تضمن ظهوره في الإجابات أو نتائج البحث. إعداد Search Console وفهرسة Google يجريان من حساب Google الخاص بالموقع، منفصلين عن نشر خريطة الموقع من Vercel. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - src/compiler/lexer.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/lexer.inc - src/compiler/compiler.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/compiler.inc - src/vm/methods.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/methods.inc - src/vm/modules.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/modules.inc # Solan AI-Readable Reference — English ## Public machine-readable entry points **Machine entry points** | Resource | Use | | --- | --- | | /llms.txt | Short index of documentation sections and canonical sources. | | /llms-full.txt | Bilingual text bundle of the site learning guide, reference pages, and source files. | | /sitemap.xml | Public indexable URLs, including documentation pages. | | /robots.txt | Public crawl policy; documentation is allowed and `/api/` is disallowed. | | /solan-repository-index.json | JSON list of public repository files and links for the source snapshot. | | GitHub | Original language source; when details conflict, inspect the linked file rather than assuming the bundle is newer. | > These endpoints make content readable and linkable; they do not guarantee that every AI provider will crawl or index it automatically. ## Recommended rules for Solan coding assistants **Code generation** - Treat Solan as its own language; do not automatically translate it into Python/JavaScript English keywords when the lexer accepts Arabic forms. - Verify a function name, signature, and receiver type in the relevant page or source file. A name in the method table is not available on every type. - Start from examples identified as README-derived, then verify against the user’s version. Samples labeled “not executed” are not execution tests. - Do not invent export rules or argument/return types where the file does not declare them. State what remains unknown. - Do not duplicate install instructions; point to `/install` and use `/docs/cli` for runtime commands. - For version-sensitive files, link a commit or inspect current GitHub and state when it was checked. ## Copyable instructions for an AI assistant **Usage prompt** The Arabic and English prompts above intentionally require source verification and disclosure of uncertainty; they do not claim that any model has special access to the website. ## Discovery does not mean automatic adoption **Reference limits** llms files and structured pages help crawlers and AI tools that visit the site, but they do not automatically add the site to model training data or guarantee inclusion in search/AI answers. Search Console ownership and Google indexing are managed in the site’s Google account, separately from publishing a Vercel sitemap. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - src/compiler/lexer.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/lexer.inc - src/compiler/compiler.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/compiler.inc - src/vm/methods.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/methods.inc - src/vm/modules.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/modules.inc # خريطة مستودع Solan — العربية ## لقطة المصدر المستخدمة **المصدر** المستودع العام هو `kingxsolo/Solan`. بُني هذا المرجع على فرع `main` عند commit `8939b6c` (إصلاح ربط padding اليسار/اليمين)، وعدد الملفات المتتبعة في تلك اللقطة 69. يعرض ملف `solan-repository-index.json` كل المسارات المسجلة وروابط GitHub المثبتة على commit اللقطة. > فهرس الملفات يضم أسماء المسارات وروابط عامة فقط، وليس نسخًا من محتويات الملفات. عند تغير `main` قد تختلف واجهات المصدر؛ راجع commit المثبت أو حدث المرجع. ## المجلدات الرئيسية **البنية** | المسار | المحتوى بحسب README | | --- | --- | | `src/compiler/` | lexer والمحلل/middle compiler وbytecode والتفكيك والتلوين. | | `src/vm/` و`src/core/` | الآلة الافتراضية، طرق الأنواع والوحدات، البيانات والذاكرة وجامع المهملات. | | `src/jit/` | المجمّع الفوري x86-64. | | `src/lib/` | الوحدات الأصلية وFFI والشبكة وSQLite والضغط والحزم وغيرها. | | `src/runtime/` و`src/platform/` | التشغيل وREPL وأدوات CLI، والاختلافات بين POSIX وWindows. | | `src/abi/` و`include/` | طبقة C ABI والرأس العام `solan.h`. | | `stdlib/` | مكتبات قياسية مكتوبة بسولان ومضمّنة في الملف التنفيذي. | | `editor/vscode/` | ملفات إضافة VS Code وقواعد التلوين والقصاصات وعميل LSP. | | `third_party/` و`tools/` | اعتماديات مضمنة وأدوات مساعدة؛ راجع ملف الفهرس لكل المسارات. | ## فهرس كل الملفات **الوصول** - يتوفر ملف JSON عام باسم `solan-repository-index.json` بجذر الموقع، ويحتوي معلومات المستودع والفرع والـcommit وقائمة كل المسارات المتتبعة مع رابط GitHub لكل ملف. - ابدأ بـREADME للتثبيت والتشغيل والقواعد، ثم صفحات `/docs` لمراجع APIs؛ لا تجعل ملف index بديلًا عن فتح الملف الأصلي عند الحاجة إلى تفاصيل التنفيذ. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - solan.c — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/solan.c - src/compiler/lexer.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/lexer.inc - src/compiler/compiler.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/compiler.inc - src/vm/vm_core.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/vm_core.inc - src/runtime/main.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/main.inc # Solan Repository Map — English ## Source snapshot used **Source** The public repository is `kingxsolo/Solan`. This reference was based on `main` at commit `8939b6c` (fixing left/right padding method bindings); that snapshot contains 69 tracked files. `solan-repository-index.json` lists tracked paths and GitHub links pinned to the snapshot commit. > The file index contains public paths and links, not copies of file contents. As `main` changes, source APIs may differ; inspect the pinned commit or refresh this reference. ## Top-level source areas **Structure** | Path | README-described contents | | --- | --- | | `src/compiler/` | Lexer/parser/compiler, bytecode, disassembly, highlighting. | | `src/vm/` and `src/core/` | VM, type methods/modules, values, memory, garbage collector. | | `src/jit/` | x86-64 just-in-time compiler. | | `src/lib/` | Native modules, FFI, network, SQLite, compression, package manager, etc. | | `src/runtime/` and `src/platform/` | Runtime, REPL, CLI tools, POSIX/Windows differences. | | `src/abi/` and `include/` | C ABI implementation and public `solan.h` header. | | `stdlib/` | Solan-written standard modules embedded in the executable. | | `editor/vscode/` | VS Code extension, syntax grammar, snippets, and LSP client. | | `third_party/` and `tools/` | Bundled dependencies and helper tools; see the index for every path. | ## Index of every file **Access** - A public `solan-repository-index.json` at the site root contains repository/branch/commit metadata and every tracked path with a GitHub file link. - Start with README for installation, runtime, and language conventions, then use `/docs` API references. The path index is not a substitute for opening source files when implementation detail is required. ### Source files - README.md — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/README.md - solan.c — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/solan.c - src/compiler/lexer.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/lexer.inc - src/compiler/compiler.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/compiler/compiler.inc - src/vm/vm_core.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/vm/vm_core.inc - src/runtime/main.inc — https://github.com/kingxsolo/Solan/blob/8939b6c35f9ce931e28f3c3cffbe53bcb50a27ad/src/runtime/main.inc