Skip to content
kingxsoloPublic

About

سولان (Solan) — لغة برمجة عربية مفتوحة المصدر بمترجم أصلي، مكتبات قياسية متكاملة، وأدوات تطوير حديثة.

Topics

Resources

Security policy

Stars

4 stars

Watchers

1 watching

Forks

Repository files navigation

سولان — لغة برمجة عربية بالكامل

سولان (Solan) — لغة برمجة عربية

سولان لغة برمجة كاملة بالعربية: كلماتها المفتاحية ودوالها ومكتباتها ورسائل أخطائها كلها عربية، وتعمل كملف تنفيذي واحد بلا مفسّر خارجي.

خل اسم = "عالم"
اطبع("مرحبا يا ${اسم}")

الإصدار الحالي: 1.4.0

هذا الملف هو التوثيق الوحيد والكامل للغة: طرق التثبيت لكل نظام، التشغيل، تعلّم اللغة، المرجع الكامل لكل دالة ومكتبة، كتابة المكتبات ونشرها وتنزيلها، الأدوات، البناء من المصدر، وسجل الإضافات والتغييرات. لا حاجة لأي ملف توثيق آخر.

الفهرس

  1. التثبيت — كل الأنظمة
  2. تشغيل اللغة
  3. تعلّم اللغة
  4. المرجع: الكلمات والمتغيرات والدوال المدمجة
  5. المرجع: المكتبات المدمجة (الأصلية)
  6. المرجع: المكتبات القياسية (المكتوبة بسولان)
  7. المرادفات
  8. الصلاحيات والأمان
  9. المكتبات والحزم: استعمالها وتنزيلها
  10. كتابة مكتبة ونشرها
  11. مكتبات أصلية بلغة C وFFI
  12. أدوات المحرر والتنسيق
  13. البناء من المصدر
  14. الاستقلالية والأداء والحدود المعروفة
  15. ما الجديد: سجل الإضافات والتغييرات

1) التثبيت — كل الأنظمة

الإصدارات الجاهزة (بلا بناء — الأسهل)

اختر نسختك وانقر الزر — كل زر ينزّل أحدث إصدار مباشرة (روابط ثابتة لا تتغير مع الإصدارات الجديدة):

منصتك التنزيل أو أمر التثبيت
🪟 ويندوز 64-بت Windows 64-bit installer — شغّل Solan-Setup-x64.exe
🪟 ويندوز 32-بت Windows 32-bit installer — شغّل Solan-Setup-x86.exe
🪟 ويندوز ARM64 Windows ARM64 installer — شغّل Solan-Setup-arm64.exe
🐧 لينكس (أي توزيعة) curl -fsSL https://raw.githubusercontent.com/kingxsolo/Solan/main/install-release.sh | sh — يكتشف نظامك ويثبّت (deb أو rpm أو استخراج مباشر)
🐧 لينكس حزمة يدوية Debian package RPM package Debian ARM64 RPM ARM64
🍎 ماك (Intel + Apple Silicon) macOS installer pkg — شغّل Solan-macos.pkg، أو نفس أمر التثبيت أعلاه

كل الملفات الجاهزة مثبّتات وحزم نظام — لا توجد نسخ أرشيفية (zip/tar.gz) في الإصدارات: لينكس وماك يُثبَّتان بأمر التثبيت أعلاه أو بحزم deb/rpm/pkg الأصلية. المُثبِّت بواجهة عربية لكل معماريات ويندوز (PATH + ربط ملفات .سو محددة تلقائياً + إزالة تثبيت)، وحزم لينكس ثابتة بلا أي مكتبات، وحزمة ماك pkg مثبّت جاهز.

لينكس وماك بأمر واحد — يكتشف نظامك ويثبّت:

curl -fsSL https://raw.githubusercontent.com/kingxsolo/Solan/main/install-release.sh | sh

ترمكس (أندرويد) — بناء من المصدر داخل الترمكس (دقائق قليلة):

git clone https://github.com/kingxsolo/Solan && cd Solan && sh install.sh

كل الملفات أيضاً في صفحة Releases. قاعدة_سريعة (مخزن مفاتيح-قيم سولاني) مضمّنة في كل الملفات.

ويندوز

أ) المُثبِّت Setup.exe (الأسهل)

  1. أنزّل Solan-1.4.0-Setup-x64.exe من صفحة Releases.
  2. شغّله — الواجهة عربية بالكامل، وتختار ما تريد:
    • إضافة سولان إلى PATH (مفعّل افتراضياً).
    • ربط ملفات .سو بسولان (فتحها من المستكشف يشغّلها).
    • أيقونة على سطح المكتب وقائمة ابدأ.
  3. انتهى. افتح نافذة طرفية جديدة واكتب solan --version.

إن ظهر تحذير SmartScreen («Windows حمى جهازك») فالملف غير موقّع رقمياً: اضغط معلومات أكثر ← تشغيل على أي حال.

إزالة التثبيت: الإعدادات ← التطبيقات ← التطبيقات المثبتة ← سولان ← إزالة.

ب) البناء الأصلي من المصدر (بلا MSYS2 ولا WSL)

git clone https://github.com/kingxsolo/Solan
cd Solan
powershell -ExecutionPolicy Bypass -File install.ps1

السكربت ينزّل مترجم MinGW محمولاً (~264MB مرة واحدة، داخل مجلد المشروع لا النظام)، يبني solan.exe ملفاً واحداً ثابتاً (static)، ويثبّته في %LOCALAPPDATA%\solan\bin ويضيفه إلى PATH، وينشئ المُثبِّت الجاهز للتوزيع. لا يحتاج صلاحيات مدير.

للتحكم الأدق استعمل pc\build-pc.ps1 مباشرة:

powershell -ExecutionPolicy Bypass -File pc\get-compiler.ps1    # مترجم محمول (مرة واحدة)
powershell -ExecutionPolicy Bypass -File pc\build-pc.ps1              # بناء 64-بت
powershell -ExecutionPolicy Bypass -File pc\build-pc.ps1 -Arch32      # بناء 32-بت (مفسَّر كامل الوظائف)
powershell -ExecutionPolicy Bypass -File pc\build-pc.ps1 -V3          # استهداف x86-64-v3 (AVX2)
powershell -ExecutionPolicy Bypass -File pc\build-pc.ps1 -Installer   # بناء + إنشاء المُثبِّت (يتطلب Inno Setup)

ملاحظات ويندوز

  • https وwss: شبكة.جلب على HTTPS تعمل بلا أي إضافات عبر عميل TLS خالص مضمّن (TLS 1.3 وTLS 1.2 مع تحقق كامل للشهادات)، وكذلك wss وجلب_متدفق والبروكسي — كل شيء مدمج. خادم TLS (خيارات شهادة/مفتاح) غير مدعوم. عند غياب شهادات النظام تُستعمل حزمة شهادات CA احتياطية مدمجة فيعمل HTTPS فوراً.
  • مسارات الحزم الطويلة: إن ظهرت مشاكل مع مسارات المكتبات، فعّل «Long Paths» أو اجعل SOLAN_HOME قصيراً (مثل C:\so).
  • 32-بت وARM64: المُثبِّت Setup-x86.exe للمعمارية 32-بت يعطي مفسَّراً كامل الوظائف (الـJIT للـ64-بت فقط)، وSetup-arm64.exe يعمل على أجهزة ويندوز على ARM (سيرفيس، لابتوبات ARM) والـJIT مفعّل عليه.
  • الأداء: نسخة ويندوز الأصلية مربوطة ثابتاً بـ -O3 وLTO ومستهدفة x86-64-v2، والـJIT مفعّل — انظر القسم 14 للأرقام المقاسة.

لينكس

أ) أمر واحد — أحدث إصدار جاهز

curl -fsSL https://raw.githubusercontent.com/kingxsolo/Solan/main/install-release.sh | sh

أمر واحد يكفي لأي توزيعة: السكربت يكتشف نظامك — على أوبونتو/ديبيان ينزّل deb ويثبّته بـapt، وعلى فيدورا/ريد هات/سوزي ينزّل rpm ويثبّته بـdnf/zypper، وعلى أي توزيعة أخرى (ألپاين، آرش...) يستخرج الملف التنفيذي الثابت من حزمة deb ويثبّته في /usr/local/bin أو ~/.local/bin (بلا صلاحيات مدير). الملف الثابت (musl static) يعمل على أي توزيعة — بلا أي مكتبات.

ب) حزمة أصلية (deb / rpm)

# دبيان / أوبونتو / منت — 64-بت
sudo apt install ./solan_1.4.0_amd64.deb

# دبيان / أوبونتو / منت — ARM64 (راسبيري باي 5، خوادم ARM)
sudo apt install ./solan_1.4.0_arm64.deb

# فيدورا / ريد هات / سنتوس — x64
sudo dnf install ./Solan-1.4.0-1.x86_64.rpm

# فيدورا / ريد هات — ARM64
sudo dnf install ./Solan-1.4.0-1.aarch64.rpm

# أوبن سوزي
sudo zypper install ./Solan-1.4.0-1.x86_64.rpm

ج) البناء من المصدر

git clone https://github.com/kingxsolo/Solan && cd Solan
sh install.sh

يكتشف السكربت توزيعتك ومدير حزمها، ويثبّت مترجم C إن نقص، ويبني الملف التنفيذي، ويثبّت في /usr/local/bin أو ~/.local/bin.

ملاحظات لينكس

  • https وwss: شبكة.جلب على HTTPS تعمل بلا أي إضافات عبر عميل TLS خالص مضمّن، وكذلك wss وجلب_متدفق والبروكسي — كل شيء مدمج. خادم TLS (خيارات شهادة/مفتاح) غير مدعوم.
  • ARM64: حزم جاهزة كاملة — solan_1.4.0_arm64.deb وSolan-1.4.0-1.aarch64.rpm للتثبيت بالنظام (راسبيري باي 5، خوادم ARM)، وأمر التثبيت أعلاه يتعرف عليها تلقائياً، والـJIT مفعّل عليها كلها.

ماك (macOS)

الملف يونيفرسال: يعمل على Intel وApple Silicon (M1/M2/M3/M4) معاً.

أ) المُثبِّت pkg

  1. أنزّل Solan-1.4.0-macos.pkg من Releases.
  2. شغّله وأكمل الخطوات — يثبّت solan في /usr/local/bin (سيطلب كلمة سر المدير).
  3. إن منع Gatekeeper الفتح (الملف غير موقّع بشهادة Apple المدفوعة)، أيٌّ من هذه يكفي:
    • زر يمين على الملف ← فتح ← فتح (مرة واحدة تكفي).
    • أو: إعدادات النظام ← الخصوصية والأمان ← «تم منع استخدام…» ← فتح على أي حال.
    • أو من الطرفية قبل الفتح: xattr -d com.apple.quarantine Solan-1.4.0-macos.pkg

ب) البناء من المصدر

git clone https://github.com/kingxsolo/Solan && cd Solan
sh install.sh

يتطلب أدوات سطر الأوامر فقط (xcode-select --install إن نقص clang).

ملاحظات ماك

  • https وwss: شبكة.جلب على HTTPS تعمل بلا أي إضافات عبر عميل TLS خالص مضمّن، وكذلك wss وجلب_متدفق والبروكسي — كل شيء مدمج. خادم TLS (خيارات شهادة/مفتاح) غير مدعوم.
  • ماك Intel وApple Silicon (M1/M2/M3/M4): JIT مفعّل على المعمارين.

ترمكس (أندرويد)

لا يوجد ملف جاهز (المعمارية ARM) — البناء من المصدر داخل ترمكس يستغرق دقائق قليلة:

pkg update
pkg install -y clang git
git clone https://github.com/kingxsolo/Solan
cd Solan
sh install.sh
  • يكتشف السكربت بيئة ترمكس تلقائياً ويثبّت في $PREFIX/bin (موجود في PATH أصلاً).
  • بلا JIT — المفسّر كامل الوظائف.
  • https يعمل بلا أي إضافات عبر عميل TLS الخالص المضمّن.
  • جرّب: solan --version ثم solan -e 'اطبع("هلا من الأندرويد")'.

BSD

من المصدر مباشرة (المفسّر كامل الوظائف):

git clone https://github.com/kingxsolo/Solan && cd Solan
sh install.sh

جدول الدعم: البيئات والمعماريات

البيئة المعمارية التثبيت JIT المفسّر
ويندوز 10/11 x64 (64-بت) Setup.exe ✓ مفعّل —
ويندوز x86 (32-بت) Setup.exe ✗ ✓ كامل
ويندوز على ARM ARM64 Setup.exe ✓ مفعّل —
لينكس x86-64 deb + rpm أو أمر التثبيت ✓ مفعّل —
لينكس ARM64 deb + rpm أو أمر التثبيت ✓ مفعّل —
لينكس (بلا مدير حزم مدعوم) x86-64 / ARM64 أمر التثبيت (استخراج مباشر) ✓ مفعّل —
لينكس 32-بت من المصدر ✗ ✓ كامل
ماك Intel pkg أو أمر التثبيت ✓ مفعّل —
ماك Apple Silicon (M1–M4) pkg أو أمر التثبيت ✓ مفعّل —
ترمكس (أندرويد) ARM من المصدر ✗ ✓ كامل
BSD x86-64 من المصدر ✗ ✓ كامل
  • نفس الشجرة المصدرية للجميع — نفس اللغة والمكتبات والبايت-كود؛ الفرق الوحيد سرعة الحلقات (JIT مقابل مفسَّر).
  • قاعدة_سريعة (مخزن مفاتيح-قيم سولاني) مضمّنة في كل الملفات الجاهزة.

المتطلبات

الشيء متى يلزم
مترجم C (gcc أو clang) للبناء فقط. لا يلزم make ولا أي أداة بناء أخرى
git (الإصدار 2.x) لأوامر الحزم add وinstall وupdate وoutdated وpublish فقط. تشغيل البرامج بعدها لا يحتاجه

الطريقة السريعة (Linux / macOS / BSD)

git clone https://github.com/kingxsolo/Solan.git solan && cd solan
sh install.sh

يكتشف السكربت نظامك ومدير الحزم، ويحاول تثبيت مترجم C الناقص فقط عند الحاجة، ثم يبني الملف التنفيذي ويثبّته في /usr/local/bin أو ~/.local/bin. المكونات الاختيارية لا تُثبّت تلقائيًا. ثم:

solan --version
solan -e 'اطبع("هلا يا عالم")'

إن ظهر تنبيه أن مجلد التثبيت ليس في PATH فأضفه:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile

خيارات install.sh

الخيار الوظيفة
--prefix DIR مكان التثبيت
--no-deps لا تحاول تثبيت المترجم تلقائيًا
--build-only ابنِ ./solan فقط بلا تثبيت
--uninstall احذف solan من مكان التثبيت
--target NAME افرض المنصة: linux أو macos أو bsd أو windows أو android (للبناء عبر منصات مع CC)
--dry-run اعرض ما سيفعله بلا تنفيذ

يحترم السكربت المتغيرات CC وCFLAGS وCPPFLAGS وLDFLAGS. أمثلة:

CC=clang sh install.sh --build-only                                     # مترجم محدد
CFLAGS="-DSOLAN_JIT=0" sh install.sh --build-only                       # بلا جيت
CC=x86_64-w64-mingw32-gcc sh install.sh --build-only --target windows   # بناء لويندوز
sh install.sh --uninstall                                               # إزالة

ويندوز عبر MSYS2 (بديل)

داخل MSYS2 UCRT64: ثبّت المترجم (pacman -S --needed mingw-w64-ucrt-x86_64-gcc) ثم نفّذ sh install.sh --target windows.

التحقق بعد التثبيت

solan --version        # solan 1.4.0
solan -e 'اطبع("هلا يا عالم")'

إن ظهر تنبيه أن مجلد التثبيت ليس في PATH فأضفه:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile

إزالة التثبيت

البيئة الطريقة
ويندوز (Setup.exe) الإعدادات ← التطبيقات ← سولان ← إزالة
ويندوز (install.ps1) احذف %LOCALAPPDATA%\solan واحذف مدخله من PATH
لينكس (deb) sudo apt remove solan
لينكس (rpm) sudo dnf remove solan
لينكس/ماك/ترمكس (يدوي أو install.sh) sh install.sh --uninstall أو احذف ملف solan من مجلد التثبيت

حل المشكلات الشائعة

المشكلة الحل
solan: command not found / «ليس أمراً داخلياً» افتح طرفية جديدة بعد التثبيت، أو أضف مجلد التثبيت إلى PATH يدوياً
ويندوز: SmartScreen يحظر Setup.exe «معلومات أكثر» ← «تشغيل على أي حال» (الملف غير موقّع رقمياً)
ماك: «لا يمكن فتحه لأنه من مطوّر غير موثوق» زر يمين ← فتح، أو xattr -d com.apple.quarantine (تفصيل في قسم ماك)
https لا يعمل يعمل افتراضياً عبر عميل TLS الخالص المضمّن؛ إن فشل فتحق من تاريخ جهاز وشهادات النظام، أو استعمل SOLAN_CA_BUNDLE لحزمة شهادات بديلة، أو SOLAN_LIBSSL لمسار OpenSSL صراحة
لينكس: «لا يمكن تنفيذ الملف» تأكد من الصلاحيات: chmod +x solan — وإن كان الجهاز ARM فهذا الملف x64، استعمل البناء من المصدر
ترمكس: فشل git clone تأكد من pkg install -y git ومن الاتصال؛ أو نزّل المستودع ZIP من GitHub

متغيرات البيئة

المتغير الوظيفة
SOLAN_HOME مكان مخزن المكتبات (الافتراضي ~/.solan)
SOLAN_PATH مسارات إضافية للبحث عن الوحدات
SOLAN_SAFE إن كانت غير فارغة وليست 0 فالتشغيل بوضع آمن (قراءة وبيئة فقط)
SOLAN_CA_BUNDLE ملف حزمة شهادات CA بديلة للتحقق (لعميل TLS الخالص)
SOLAN_JIT 0 لتعطيل المجمّع الفوري وقت التشغيل
NO_COLOR لتعطيل الألوان في الطرفية
PREFIX يحدد مكان تثبيت الملف التنفيذي

2) تشغيل اللغة

تشغيل ملف أو كود

solan ملف.سو              # تشغيل ملف (الامتدادات: .سو و .an و .solan)
solan ملف.سو وسيط1 وسيط2  # الوسائط تظهر في المتغير العام «وسائط»
solan -e 'اطبع(1 + 2)'    # تشغيل كود مباشر
solan                      # الوضع التفاعلي (REPL)

في الوضع التفاعلي يُعرض ناتج كل تعبير تلقائياً، ويدعم الإدخال متعدد الأسطر (الأقواس غير المغلقة تُكمَل بسطر ...)، والتاريخ إن توفرت readline. للخروج اكتب خروج أو exit أو اضغط Ctrl+D.

يجوز أن يبدأ الملف بسطر #!/usr/bin/env solan ليكون قابلاً للتنفيذ مباشرة.

كل أوامر وخيارات سطر الأوامر

الأمر الوظيفة
solan ملف.سو [وسائط...] تشغيل ملف
solan -e "كود" تشغيل كود مباشر
solan الوضع التفاعلي
solan --check ملف.سو فحص الصياغة بلا تشغيل (يطبع «سليم» أو الخطأ)
solan fmt ملف.سو [-w] تنسيق الكود: إزاحة مسافتين لكل مستوى، حذف الفراغات الزائدة في نهاية الأسطر وتقليص الأسطر الفارغة المتكررة (-w يكتبه في الملف، وإلا يطبعه)
solan fmt ملف.سو --قياسي [-w] استبدال مرادفات الكلمات المفتاحية بالكلمة القياسية (انظر المرادفات)
solan --لون ملف.سو عرض الكود ملوّناً في الطرفية (--html يصدّر صفحة HTML)
solan --تتبع ملف.سو طباعة كل سطر ينفَّذ
solan --تصحيح ملف.سو [--نقطة N] مصحّح تفاعلي خطوة بخطوة (ونقطة توقف عند السطر N)
solan --ops ملف.سو عرض التعليمات الداخلية المترجمة (للمطورين)
solan lsp خادم اللغة (LSP) للمحررات
solan -v / --version الإصدار
solan -h / --help المساعدة
solan init · add · install · remove · update · list · outdated · why · verify · prune · cache clean · publish أوامر الحزم (القسم 9)

خيارات عامة تُوضع قبل اسم الملف:

الخيار الوظيفة
--اسمح=... / --امنع=... الصلاحيات (القسم 8)
--آمن وضع آمن: قراءة وبيئة فقط
--حد_وقت N إنهاء البرنامج بعد N ثانية
--حد_ذاكرة N حد الذاكرة بالميغابايت
--بلا_لون تعطيل الألوان
--تحذيرات جديد في 1.4.0: تفعيل تحذيرات المترجم (مثل متغيرات غير مستعملة، وأسماء مظللة) إلى المجرى الخطأي — مفيد لتشطيب الشيفرة

الأسماء الإنجليزية المكافئة: --trace و--debug و--safe و--allow و--deny و--timeout و--max-mem و--no-color و--break و--color و--warn.

رموز الخروج

0 نجاح · 65 خطأ في الصياغة · 66 تعذّر فتح الملف · 70 خطأ تشغيل غير ممسوك · 64 خيار صلاحيات غير صالح. وللخروج برمز مخصص من البرنامج: نظام.اخرج(رمز).

أول برنامج

أنشئ ملفاً هلا.سو:

خل اسم = ادخل("ما اسمك؟ ")
اطبع("أهلا يا ${اسم}!")
لكل ر في مدى(1, 4) {
  اطبع("العدّ ${ر}")
}

ثم solan هلا.سو.


3) تعلّم اللغة

كل الأمثلة هنا جُرِّبت فعلاً. المخرجات المكتوبة بعد // هي ما يطبعه البرنامج.

3.1) الأساسيات

التعليقات: // سطر و/* متعدد الأسطر */.

الفاصلة المنقوطة اختيارية. نهاية السطر تكفي، ويجوز وضع أكثر من تعليمة في سطر بـ ; (أو ؛). الفاصلة العربية ، تعمل مثل ,.

الأسماء: حروف عربية أو لاتينية وأرقام و_، ولا تبدأ برقم. اللغة تطبّع الأسماء: لا فرق بين أ وإ وآ وا، ولا بين ة وه، ولا بين ى وي، ولا التشكيل. فـ قيمة وقيمه اسم واحد (وهذا يظهر في رسائل الأخطاء وفي نوع() لأسماء الأصناف: قطة تظهر قطه). النصوص بين علامات الاقتباس لا تُطبَّع.

المتغيرات والثوابت:

خل اسم = "سلمى"        // متغير
ثابت باي_تقريبي = 3.14  // ثابت: محاولة إعادة إسناده خطأ صياغة قبل التشغيل
اسم = "ليلى"           // إعادة الإسناد مسموحة للمتغير
خل س                    // بلا قيمة ابتدائية = عدم

الأنواع الأساسية:

النوع أمثلة نوع(x)
رقم (عشري مزدوج) 5 3.5 1e3 0xFF 1_000_000 ٣٫٥ رقم
نص "سلام" 'سلام' «سلام» نص
منطقي صح غلط منطقي
عدم عدم عدم
قائمة [1, 2, 3] قائمة
قاموس {"أ": 1} قاموس
دالة دالة() { } دالة
وعد وعد() وعد
كائن من صنف قطة("ميمي") اسم الصنف

الأرقام كلها أعداد عشرية مزدوجة (double): الأعداد الصحيحة دقيقة حتى 9007199254740992، وما فوقها يرفضه المحلل (استعمل مكتبة ضخم). يمكن كتابة الأرقام بالأرقام الهندية ٠-٩ والفارسية ۰-۹ و٫ فاصلة عشرية، و_ للفصل داخل الأرقام. لعرض ناتج الأرقام هندية استعمل ارقام_الاخراج("عربي").

النصوص:

خل ن = "سلمى"
اطبع("مرحبا ${ن}، ${2 + 3} أيام")    // مرحبا سلمى، 5 أيام   ← ${...} تقبل أي تعبير
اطبع("سطر1\nسطر2\tتاب \"اقتباس\" \\ \$")  // الهروب: \n \t \" \\ \$
اطبع("نص طويل
على عدة أسطر")                        // النص يمتد عبر الأسطر
اطبع("ab" * 3, "أ" + "ب")              // ababab أب

لا تحويل ضمني بين النص والرقم: "أ" + 1 يرمي خطأ. استعمل "أ" + نص(1) أو "أ${1}". المقارنة بين نوعين مختلفين لا تتحقق ("1" == 1 غلط).

العوامل (من الأقوى ارتباطاً إلى الأضعف تقريباً):

العامل المعنى
** أس (2 ** 10 = 1024)
* × / ÷ \ % ضرب، قسمة عشرية، قسمة صحيحة (7 \ 2 = 3 و-7 \ 2 = -4)، باقي (-5 % 3 = 1: باقي موجب كما في بايثون)
+ - جمع وطرح (والجمع يدمج النصوص والقوائم)
<< >> & ^ | عمليات على البتات
< <= > >= == != مقارنة (القوائم والقواميس تُقارَن بالمحتوى)
في عضوية: "ب" في "أبج" وس في قائمة و"مفتاح" في قاموس
ليس ! نفي منطقي
و && «و» (كسولة)
او || «أو» (كسولة)
? : أو ؟ : الشرط الثلاثي: شرط ? أ : ب
?? أو ؟؟ القيمة الافتراضية إن كان اليسار عدم: س ?? "افتراضي"
?. أو ؟. وصول آمن: م?.أ يعطي عدم إن كان م عدماً (لا يحمي من مفتاح مفقود في قاموس)
= += -= *= /= \= %= **= ++ -- الإسناد

الصحة والخطأ المنطقي: القيم «الكاذبة» هي غلط وعدم و0 والنص الفارغ "" والقائمة الفارغة والقاموس الفارغ؛ ما سواها «صادق».

3.2) الشروط

خل أ = 7
اذا أ > 100 {
  اطبع("مئة")
} والا_اذا أ > 5 {
  اطبع("أكبر من خمسة")
} والا {
  اطبع("لا")
}
اطبع(أ > 5 ? "كبير" : "صغير")

التبديل (لا يسقط من حالة لأخرى؛ كل حالة كتلة مستقلة، وتقبل عدة قيم):

تبديل أ {
  حالة 1 { اطبع("واحد") }
  حالة 2, 3 { اطبع("اثنان أو ثلاثة") }
  افتراضي { اطبع("غير ذلك") }
}

أنماط النوع والمدى (جديدة في 1.4.0): حالة تقبل نوعاً مدمجاً أو مدىً رقمي:

دالة صف(س) {
  تبديل س {
    حالة نص { ارجع "نص" }            // نمط نوع: نص، رقم، عدد_صحيح، منطقي، قائمة، قاموس، دالة، كائن، صنف، كوروتين
    حالة مدى(10, 20) { ارجع "وسط" }  // نمط مدى: صحيح إذا كان 10 <= س <= 20 (الطرفان شاملان)
    حالة رقم { ارجع "رقم" }
    افتراضي { ارجع "آخر" }
  }
}
صف("مرحبا")   // نص
صف(15)        // وسط
صف(5)         // رقم

ملاحظة: حالة رقم تطابق أي رقم (وليس الصحيح فقط)، وترتيب الحالات مهم — ضع الأنماط الأخص (مدى) قبل الأعم (رقم). كما أن نمط مدى يفحص الأرقام فقط: القيمة غير الرقمية لا تدخله ولا تدخل افتراضي خطأً — بل تجاهَل النمط.

3.3) الحلقات

طالما س < 3 { س++ }                  // طالما: ما دام الشرط صادقاً
كرر 3 { اكتب("ه") }                  // كرر N مرة: ههه
لكل ر في مدى(0, 10, 4) { اطبع(ر) }  // 0 ثم 4 ثم 8  (مدى(أ، ب، خطوة): الخطوة اختيارية وقد تكون سالبة)
لكل ح في "سلام" { اطبع(ح) }          // على حروف النص
لكل ع في [10, 20] { اطبع(ع) }
لكل ك, ق في {"x": 1, "y": 2} { اطبع(ك, ق) }   // x 1 ثم y 2  (مفتاح وقيمة)
لكل ف, ق في ["a", "b"] { اطبع(ف, ق) }         // 0 a ثم 1 b  (فهرس وقيمة)

توقف تخرج من الحلقة واستمر تنتقل إلى التكرار التالي. مدى داخل لكل كسولة ولا تبني قائمة (يمكن مدى(0, 30000000))، أما خارج لكل فتبني قائمة (حدها 10 ملايين عنصر).

3.4) الدوال

دالة جمع(أ, ب = 2) { ارجع أ + ب }       // معامل افتراضي
اطبع(جمع(1), جمع(1, 5))                   // 3 6

دالة مجموع(...ارقام) {                    // معاملات متبقية ...
  خل ج = 0
  لكل ر في ارقام { ج += ر }
  ارجع ج
}
اطبع(مجموع(1, 2, 3), مجموع(...[4, 5]))   // 6 9   ← ... في الاستدعاء تفرد القائمة

خل ضعف = دالة(س) { ارجع س * 2 }          // دالة مجهولة
خل ثلاثة = (س) => س * 3                  // دالة سهمية (التعبير هو الناتج)
خل اربعة = س => س * 4

دالة عداد() {                             // إغلاقات (closures)
  خل ع = 0
  ارجع دالة() { ع++; ارجع ع }
}
خل ع1 = عداد(); ع1()
اطبع(ع1())                                // 2

الدوال قيم عادية: تُمرَّر وتُعاد وتُخزَّن. دالة بلا ارجع تعيد عدم. الدوال يمكن أن تتداخل. ملاحظة: أسماء مثل و واو وليس وفي كلمات محجوزة ولا تصلح اسماء معاملات أو متغيرات.

الأنواع الاختيارية (تُفحص وقت التشغيل، وتُحذف بلا أثر إن لم تكتبها):

خل س: رقم = 5
دالة جمع2(أ: رقم, ب: رقم = 2): رقم { ارجع أ + ب }
دالة اسم(ن: نص? = عدم): نص { ارجع ن ?? "افتراضي" }   // ? تعني: أو عدم
خل م: رقم | نص = "ا"                                    // اتحاد أنواع
خل ق: قائمة<رقم> = [1, 2]                               // يُفحص الحاوية فقط لا العناصر
خل ز = (أ: رقم): رقم => أ * 2

الأنواع العامة العميقة (جديدة في 1.4.0): تدوين <> يفحص العناصر أيضاً وليس الحاوية فقط:

دالة مجموع_قائمة(ق: قائمة<رقم>): رقم { خل م = 0; لكل س في ق { م += س } ارجع م }
مجموع_قائمة([1, 2, 3])        // 6
مجموع_قائمة(["أ"])             // خطأ وقت التشغيل: المعامل 'ق' يتوقع 'قائمة<رقم>' لكن وجدت 'قائمة'
خل د: قاموس<نص, رقم> = {"عمر": 30}   // المفتاح نص والقيمة رقم

عمق الفحص حتى 8 مستويات (قائمة<قائمة<رقم>> تعمل)، والقواميس العامة تفحص المفتاح والقيمة معاً. ويجب أن تحتوي قائمة على مواصفة عنصر واحدة، وقاموس على مواصفة مفتاح وقيمة؛ والاتحادات مثل قائمة<رقم | نص> مدعومة.

الواجهات (جديدة في 1.4.0): واجهة تعرّف عقداً من الطرق بلا أجسام، ويطبق(كائن, واجهة) تفحص تحقيقه:

واجهة شكل {
  دالة مساحة()
  دالة محيط()
}
صنف دائرة {
  بناء(ن) { هذا.ن = ن }
  دالة مساحة() { ارجع 3.14 * هذا.ن * هذا.ن }
  دالة محيط() { ارجع 2 * 3.14 * هذا.ن }
}
خل د = دائرة(5)
اطبع(يطبق(د, شكل))        // صح — الكائن يملك كل طرق الواجهة
اطبع(يطبق(دائرة, شكل))    // صح — تعمل على الصنف أيضاً

طريقة واجهة بلا جسم تُجمَّع تلقائياً (استدعاؤها المباشر يرمي خطأً واضحاً)، وتُقارن تواقيع التنفيذ مع الواجهة بحيث يقبل التنفيذ معاملات الواجهة ضمن نطاقه (ويجوز أن يقدّم معاملات اختيارية إضافية)، وبحسب كون الطريقة متبقية أو خاصية getter أو غير متزامنة/مولّدة. أنواع المعاملات وقيمة الإرجاع توثيقية حالياً ولا تدخل في مطابقة يطبق. والواجهة صنف عادي داخلياً، فيمكن وراثتها.

الأنواع المعروفة: رقم (= عدد)، عدد_صحيح، نص، منطقي، قائمة، قاموس، دالة، عدم، اي، كائن، صنف، كوروتين، وأي اسم صنف (يشمل الأصناف الوارثة). عند المخالفة: خطأ في النوع: المتغير 'س' يتوقع 'رقم' لكن وجدت 'نص'.

3.5) القوائم

خل ق = [3, 1, 2]
اطبع(ق[0], ق[-1], ق.طول, طول(ق))     // 3 2 3 3   (الفهرس السالب من النهاية)
ق[0] = 9
خل [أ, ب] = [1, 2]                      // تفكيك عند التعريف
[أ, ب] = [ب, أ]                          // تبديل قيمتي متغيرين (تفكيك بالإسناد)
خل ك = [...[1, 2], 3, ...[4]]           // [1، 2، 3، 4]  (نشر القوائم)
اطبع([1] + [2], [0] * 3)                // [1، 2]  [0، 0، 0]

الفهرس خارج النطاق يرمي خطأ: فهرس القائمة غير صالح أو خارج النطاق. طرق القوائم في القسم 4.

3.6) القواميس

خل م = {"أ": 1, "ب": 2}
اطبع(م["أ"], م.أ)                       // 1 1   (الوصول بالنقطة للمفاتيح النصية)
م["ج"] = 3
اطبع("ب" في م, م.احصل("د", 0))          // صح 0   (احصل مع قيمة افتراضية)
خل {الاسم, العمر} = {"الاسم": "سلمى", "العمر": 30}    // تفكيك قاموس
خل ن = {...م, "ه": 5}                   // نشر قاموس

ترتيب الإدخال محفوظ. المفتاح غير الموجود يرمي خطأ (المفتاح 'ب' غير موجود في القاموس)، فاستعمل .احصل(مفتاح، افتراضي) أو في للفحص قبل القراءة. المفاتيح يمكن أن تكون نصوصاً أو أرقاماً.

3.7) الأصناف والوراثة

صنف حيوان {
  دالة بناء(اسم) { هذا.اسم = اسم }          // المُنشئ اسمه «بناء»
  دالة صوت() { ارجع "..." }
  دالة عرف() { ارجع هذا.اسم + " يقول " + هذا.صوت() }
  ساكن دالة نوع_عام() { ارجع "حيوان" }       // عضو ساكن (يُستدعى على الصنف)
  خاصية الاسم_كبير() { ارجع هذا.اسم.كبير() } // خاصية (getter) بلا أقواس عند القراءة
}
صنف قطة يرث حيوان {                          // أو: صنف قطة : حيوان
  دالة صوت() { ارجع "مياو" }
  دالة عرف() { ارجع الاب.عرف() + "!" }      // الاب = الصنف الأب
}
خل ق = قطة("ميمي")
اطبع(ق.عرف())                                // ميمي يقول مياو!
اطبع(حيوان.نوع_عام(), ق.الاسم_كبير)         // حيوان ميمي
اطبع(هل_فرع(ق, حيوان), نوع(ق), لديه(ق, "اسم"))   // صح قطه صح

هذا هو الكائن الحالي. الخصائص تُنشأ بالإسناد هذا.س = ... داخل بناء أو أي دالة. استدعاء صنف بوسائط وهو بلا بناء خطأ.

3.8) التعداد

تعداد لون { احمر, اخضر = 5, ازرق }
اطبع(لون.احمر, لون.اخضر, لون.ازرق)   // 0 5 6   (يستمر العدّ بعد القيمة المحددة)

3.9) معالجة الأخطاء

حاول {
  ارمي "خطأ تجريبي"             // ارمي: يمكن رمي أي قيمة (غالباً نص)
} امسك (خ) {                      // الأقواس حول اسم المتغير اختيارية
  اطبع("امسكت:", خ)
} اخيرا {
  اطبع("تنفَّذ دائماً")
}

أخطاء التشغيل الداخلية تُمسَك كنصوص عربية: القسمة على صفر والمفتاح 'ب' غير موجود في القاموس والمتغير 'س' غير معرّف ولا يمكن الطرح بين 'نص' و 'رقم'. الخطأ غير الممسوك يطبع رسالة مع رسم للسطر ومكدس الاستدعاء وينهي البرنامج برمز 70. تأكد(شرط، رسالة) يرمي الرسالة إن كان الشرط كاذباً.

صنف خطأ المنظّم (جديد في 1.4.0): يمكنك رمي ومسك أخطاء بكائنات منظمة بدل نصوص:

حاول {
  ارمي خطأ("المبلغ غير كافٍ", "مالية", 12, "دفتر.سو")
} امسك (خ) {
  اطبع(خ.رسالة)   // المبلغ غير كافٍ
  اطبع(خ.نوع)     // مالية  (افتراضياً "مستخدم")
  اطبع(خ.سطر)     // 12
  اطبع(خ.ملف)     // دفتر.سو
}

التوقيع: خطأ(رسالة, نوع = "مستخدم", سطر = 0, ملف = ""). كما أن أخطاء النوع وقت التشغيل (مخالفة تعليقات : الأنواع) تُرمى الآن ككائنات خطأ أيضاً (.نوع = "نوع")، فتستطيع فحص خ.نوع بدل تحليل النص. مسك خطأ نصي أو كائني يعمل بنفس الصيغة حاول/امسك.

3.10) المولّدات والكوروتينات

مولد دالة عد(ن) {                      // دالة مولّدة: تنتج قيماً واحدة بعد أخرى
  لكل ي في مدى(0, ن) { انتج ي }
}
لكل ع في عد(3) { اطبع(ع) }             // 0 1 2

خل ر = كوروتين(دالة() { انتج 1; انتج 2; ارجع 3 })    // كوروتين يدوي
اطبع(استأنف(ر))   // 1
اطبع(استأنف(ر))   // 2
اطبع(منتهي(ر))    // غلط (ينتهي بعد الاستئناف الثالث)

3.11) البرمجة غير المتزامنة

غير_متزامن دالة تعيد وعداً، وانتظر توقف الدالة حتى يكتمل الوعد. حلقة أحداث واحدة تدير كل شيء (مؤقتات، شبكة، عمليات فرعية) بلا خيوط.

غير_متزامن دالة مهمة(اسم, ثواني) {
  انتظر نم(ثواني)                       // نم: وعد ينتهي بعد المدة
  ارجع "انتهت ${اسم}"
}
غير_متزامن دالة رئيسي() {
  خل نتائج = انتظر كل_الوعود([مهمة("أ", 0.3), مهمة("ب", 0.3)])   // بالتوازي: ~0.3 ثانية
  اطبع(نتائج)
  اطبع(انتظر عملية(دالة() { ارجع 6 * 7 }))   // عملية ثقيلة في عملية فرعية: 42
}
شغل(رئيسي)                              // شغل: يشغّل الدالة وينتظر انتهاءها

المرجع الكامل للوعود (وعد و.ثم و.التقط وكل_الوعود وسباق...) في القسم 4. وللعمل الموازي على أنوية المعالج انظر مكتبة عمال.

إلغاء الوعود (جديدة في 1.4.0):

غير_متزامن دالة رئيسي() {
  خل وع = وعد()
  وع.عند_الغاء(دالة() { اطبع("نظّف الموارد") })   // تُستدعى عند الإلغاء
  وع.ألغِ()                                        // يعلّم الوعد ملغىً ويستدعي ردود الإلغاء
  اطبع(وع.ملغى)                                    // صح

  خل م = وعد()
  خل ن = م.مع_مهلة(2)                              // وعد جديد: يفشل بعد ثانيتين إن لم يكتمل م
  // عند تجاوز المهلة: يُلغى م وتُستدعى ردوده، لكن ن يفشل بخطأ نوعه "مهلة"
  // ن.ملغى == غلط؛ فهذا فشل بسبب المهلة وليس إلغاءً صريحاً لـن
}
شغل(رئيسي)
العضو الجديد الوظيفة
.ألغِ() يلغي الوعد (يعلّمه منجزاً فاشلاً ملغىً بخطأ "أُلغيت المهمة") ويستدعي ردود الإلغاء
.عند_الغاء(دالة) يسجّل دالة تُستدعى عند الإلغاء (أو فوراً إن كان ملغىً سابقاً)
.مع_مهلة(ثواني) يعيد وعداً جديداً يُرفض بخطأ نوعه "مهلة" إن لم يكتمل الأصل خلال المدة، ويلغي الأصل عندئذٍ (فيصبح الأصل ملغى، أما الوعد المعاد فيكون فاشلاً لا ملغى)
.ملغى خاصية: هل أُلغي الوعد

ملاحظة ويندوز: تهيئة Winsock كسولة؛ لا تُجرى إلا عند أول استخدام فعلي للشبكة، وتُعاد تهيئتها بأمان في عمليات العمال الفرعية. استدعاء سوكت.استمع يستدعي ذلك. عملية(دالة) (النسخة المدمجة غير المتزامنة، وليس نظام.عملية التي تأخذ أمراً نصياً) تشغّل الدالة في عملية فرعية حقيقية. أي دالة تُمرَّر لـعملية أو عمال في ويندوز تُجمَّد (globals + closures) — ولا يمكن تجميد كائنات الأصناف، لذا لا تعرّف صنف/واجهة في ملف يستعملها، واستعمل دوالاً وقوائم وقواميس فقط في الدالة المرسلة.

3.12) الوحدات والاستيراد

الاستيراد يكون في المستوى الأعلى للملف فقط:

استورد "رياضيات"                        // مكتبة مدمجة أو قياسية
اطبع(رياضيات.جذر(16))                   // 4

استورد "رياضيات" باسم ر                 // باسم آخر
من "رياضيات" استورد جذر, باي            // استيراد أسماء محددة
من "رياضيات" استورد جذر باسم ج, باي

استورد "./وحدة"                         // ملف نسبي (يُربط باسم الملف: وحدة)
استورد "./مجلد/اداة" باسم اداة

كل ما يُعرَّف في المستوى الأعلى من الملف يصبح عضواً في الوحدة (دوال ومتغيرات وأصناف). لا توجد كلمة export. ملف وحدة.سو:

خل ثابتي = 5
دالة سلم() { ارجع "من الوحدة" }
اذا هو_الرئيسي { اطبع("اشتغلت مباشرة") }   // يُنفَّذ فقط عند تشغيل الملف مباشرة لا عند استيراده
  • المتغير العام هو_الرئيسي يكون صح في الملف المشغَّل مباشرة وغلط في الوحدات المستوردة.
  • الوحدة تُحمَّل مرة واحدة وتُخزَّن. الاستيراد الدائري آمن (لا حلقة لا نهائية).
  • يُبحث عن الاسم بهذا الترتيب: مسار نسبي ← مكتبة مدمجة/قياسية ← اعتماديات المشروع من solan.lock ← المسارات القديمة (SOLAN_PATH ثم ~/.solan/modules/ ثم $PREFIX/lib/solan/). والامتدادات المجرَّبة: بلا امتداد، .سو، .an، .solan، ثم مجلد فيه رئيسي.سو.
  • الاستيراد النسبي داخل مكتبة يُحسب نسبةً إلى الملف الذي فيه الاستيراد.

3.13) أنماط شائعة

قراءة وكتابة ملف:

استورد "ملفات"
ملفات.اكتب("ملاحظات.txt", "سطر1\nسطر2\n")
ملفات.الحق("ملاحظات.txt", "سطر3\n")
لكل س في ملفات.سطور("ملاحظات.txt") { اطبع(س) }

JSON:

استورد "جيسون"
خل نص_ج = جيسون.ترميز({"أ": [1, 2, {"ب": صح}]})
اطبع(نص_ج)                 // {"أ":[1,2,{"ب":true}]}
اطبع(جيسون.فك(نص_ج).أ[1]) // 2

طلب HTTP:

استورد "شبكة"
خل ر = شبكة.جلب("https://api.example.com/data", {"رؤوس": {"Accept": "application/json"}})
اذا ر.ناجح { اطبع(جيسون.فك(ر.جسم)) } والا { اطبع("فشل:", ر.حالة) }

خادم ويب صغير:

استورد "شبكة"
دالة معالج(طلب) {
  اذا طلب.مسار == "/api" { ارجع {"جسم": {"طريقة": طلب.طريقة}} }   // قاموس في الجسم يُرسَل JSON
  ارجع "<h1>مرحبا ${طلب.استعلام.احصل("اسم", "يا غريب")}</h1>"      // نص يُرسَل HTML
}
شبكة.خادم(8080, معالج)

4) المرجع: الكلمات والمتغيرات والدوال المدمجة

4.1) الكلمات المفتاحية

كل كلمة تقبل مرادفات (القسم 7) ولا فرق في الهمزات ولا ة/ه. هذه الكلمات القياسية:

الكلمة الوظيفة
خل تعريف متغير
ثابت تعريف ثابت
دالة تعريف دالة
ارجع إرجاع قيمة من دالة
اذا · والا_اذا · والا الشرط
طالما حلقة بشرط
كرر تكرار عدد مرات
لكل … في حلقة على عناصر
توقف · استمر الخروج من الحلقة / التكرار التالي
تبديل · حالة · افتراضي تبديل متعدد الحالات (حالة وافتراضي سياقيتان)
تعداد تعريف تعداد
صح · غلط · عدم القيم الثابتة
و · او · ليس العوامل المنطقية
صنف · هذا · الاب · يرث الأصناف (وساكن وخاصية سياقيتان)
حاول · امسك · اخيرا · ارمي الأخطاء
استورد · باسم · من الاستيراد (من سياقية)
غير_متزامن · انتظر البرمجة غير المتزامنة
مولد · انتج المولّدات

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

4.2) المتغيرات العامة (متاحة دائماً)

الاسم القيمة
وسائط قائمة نصوص: وسائط سطر الأوامر بعد اسم الملف
هو_الرئيسي صح إن كان الملف مشغَّلاً مباشرة، غلط إن كان مستورداً
اسم_الملف اسم الملف المشغَّل
النسخة نص إصدار اللغة (1.4.0)
نظام · جيسون · شبكة · سوكت · حلقة هذه المكتبات الخمس مستوردة تلقائياً (لا تحتاج استورد)
وعد صنف الوعود (انظر 4.4)
خطأ صنف الأخطاء المنظّمة: خطأ(رسالة, نوع؟, سطر؟, ملف؟) (انظر 3.9)
بعض(ق) · فارغ_اختياري() · هل_اختياري(ق) نوع اختياري الجاهز: بعض(5).افتح() ← 5، .او(بديل) يعيد القيمة أو البديل، نص(فارغ_اختياري()) ← لا_شيء
مجموعة([عناصر؟]) بنية مجموعة (Set): .اضف (تُرجع هذا للتسلسل) .يحتوي .احذف .حجم .فارغ .الى_قائمة .لكل .اتحاد .تقاطع .فرق، والنص مجموعة{1, 2} — .حجم و.فارغ خاصيتان
طابور() بنية طابور FIFO: .اضف .اسحب (يسحب من الأمام) .حجم .فارغ — خاصيتان
مكدس() بنية مكدس LIFO: .اضف .اسحب .قمة .حجم .فارغ — خاصيتان
من_ازواج(قائمة_أزواج) قاموس من قائمة أزواج [مفتاح, قيمة]: من_ازواج([["أ", 1], ["ب", 2]])
اجمع_القمامة() يشغّل جمع القمامة يدوياً ويعيد عدد الكائنات الحية بعد الجمع
عدد_الكائنات() عدد الكائنات الحية حالياً في الذاكرة
حد_القمامة(حد؟) يقرأ عتبة جمع القمامة (بالبايت)، ويعيدها بوسيط جديد
يطبق(كائن, واجهة) هل يملك الكائن (أو صنفه) كل طرق الواجهة (انظر 3.4)
هل_فرع(كائن, صنف) كما سبق — يعمل أيضاً مع الواجهات

4.3) الدوال المدمجة

الدالة الوظيفة
اطبع(...قيم) تطبع القيم مفصولة بمسافة وتنهي بسطر جديد
اكتب(...قيم) مثل اطبع بلا سطر جديد
ادخل(سؤال؟) تقرأ سطراً من الإدخال (تعرض سؤال أولاً إن أُعطي). تعيد عدم عند نهاية الإدخال
طول(x) عدد حروف النص / عناصر القائمة / مفاتيح القاموس
نوع(x) اسم النوع: رقم نص منطقي قائمة قاموس عدم دالة وعد، أو اسم الصنف لكائنات الأصناف
نص(x) تحويل أي قيمة إلى نص
رقم(x) تحويل نص إلى رقم (يعيد عدم إن لم يكن رقماً)، ورقم(صح) = 1
مدى(نهاية) · مدى(بداية, نهاية) · مدى(بداية, نهاية, خطوة) قائمة أرقام (النهاية مستثناة، الخطوة قد تكون سالبة). كسولة داخل لكل
تأكد(شرط, رسالة؟) ترمي الرسالة إن كان الشرط كاذباً
حرف(رمز) · رمز(حرف) الحرف من رمزه (حرف(65) = A) والعكس
هل_نص(x) هل_رقم(x) هل_قائمة(x) هل_قاموس(x) هل_عدم(x) هل_دالة(x) هل_وعد(x) فحص النوع
هل_فرع(كائن, صنف) هل الكائن من الصنف أو من وارث منه
لديه(كائن, اسم) هل لكائن الصنف هذه الخاصية أو الدالة
نسق(قالب, ...قيم) تنسيق نص (انظر أدناه)
لون_الكود(نص) · كود_html(نص) تلوين شيفرة سولان بألوان الطرفية (ANSI) أو بصفحة HTML
ارقام_عربية(نص) · ارقام_لاتينية(نص) · ارقام_فارسية(نص) تحويل الأرقام داخل نص إلى هندية / لاتينية / فارسية
ارقام_الاخراج(نمط) يغيّر طريقة عرض الأرقام في كل المخرجات: "عربي" (أو "ar") هندية، "فارسي" (أو "fa") فارسية، وأي شيء آخر لاتينية
كوروتين(دالة) ينشئ كوروتيناً من دالة تستعمل انتج
استأنف(كوروتين, قيمة؟) يكمل الكوروتين حتى انتج التالي ويعيد القيمة المنتَجة
منتهي(كوروتين) هل انتهى الكوروتين
وعد() ينشئ وعداً جديداً (انظر 4.4)
نم(ثواني) وعد ينتهي بعد المدة (مع انتظر)
كل_الوعود(قائمة) وعد يكتمل حين تكتمل كلها، ونتيجته قائمة النتائج بنفس الترتيب (العناصر غير الوعود تُقبل كما هي)
سباق(قائمة) وعد يكتمل بنتيجة أول وعد ينتهي
شغل(دالة) يشغّل الدالة، وإن أعادت وعداً ينتظره ويعيد نتيجته (نقطة بداية البرامج غير المتزامنة)
عملية(دالة) يشغّل الدالة في عملية فرعية ويعيد وعداً بنتيجتها (النتيجة يجب أن تكون قابلة لترميز JSON)
جلب_غير_متزامن(رابط, خيارات؟) شبكة.جلب لكن بوعد (لا يحجب الحلقة)
خادم_حلقة(منفذ, معالج, خيارات؟) خادم HTTP على حلقة الأحداث، والمعالج قد يكون غير_متزامن (وهو نفسه شبكة.خادم_حلقة)

دوال رياضية عامة (جديدة في 1.1.0): هذه الدوال متاحة الآن مباشرة بلا استورد "رياضيات": جذر قرب ارضي سقف بتر مطلق قوة لوغ اكبر اصغر — اطبع(جذر(16), قوة(2, 10)) ← 4 1024. وتظل متاحة عبر الوحدة رياضيات كذلك.

قوالب نسق:

القالب المعنى مثال الناتج
{} القيمة التالية نسق("{} من {}", 3, 10) 3 من 10
{0} {1} قيمة بالترتيب نسق("{0} {1} {0}", "أ", "ب") أ ب أ
{:.2f} عشري بعدد خانات نسق("{:.2f}", 3.14159) 3.14
{:5} {:<5} {:>5} {:^5} عرض: افتراضي، يسار، يمين، وسط `نسق("{:>5} {:<5}
{:05d} صحيح بأصفار بادئة نسق("{:05d}", 42) 00042
{:x} {:b} ست عشري، ثنائي نسق("{:x} {:b}", 255, 5) ff 101

طرق الأرقام الجديدة في 1.4.0 (تُستدعى على الرقم مباشرة، وتكمل دوال رياضيات العامة):

الطريقة الوظيفة
.قيمة_مطلقة() القيمة المطلقة: (-5).قيمة_مطلقة() ← 5
.أرضية() · .سقف() · .قرّب() · .اقطع() تقريب لأسفل / لأعلى / لأقرب صحيح / حذف الجزء الكسري
.جذر() الجذر التربيعي (يخطئ على السالب)
.هل_صحيح() هل الرقم صحيح (بلا جزء كسري): 5.هل_صحيح() ← صح
.هل_غير_معرف() هل القيمة NaN
.هل_لانهائي() هل القيمة لانهائية (أو NaN)
.عدد_الى_حروف() الرقم كتابةً بالعربية (صحيح من 0 إلى 999999): 125.عدد_الى_حروف() ← مئة وخمسة وعشرون
.حول_ارقام_عربية() يمثّل الرقم بأرقام عربية-هندية نصاً: 56.حول_ارقام_عربية() ← ٥٦

4.4) الوعود

الوعد كائن من الصنف وعد يمثل نتيجة ستصل لاحقاً.

العضو الوظيفة
وعد() وعد جديد غير مكتمل
.حل(قيمة) يكمله بالقيمة (ويعيد الوعد نفسه)
.ارفض(خطأ) يكمله بفشل
.ثم(دالة) وعد جديد نتيجته دالة(القيمة)
.التقط(دالة) وعد جديد يعالج الفشل: نتيجته دالة(الخطأ)
.منجز · .قيمة · .فشل · .خطأ الحالة: هل اكتمل، قيمته، هل فشل، سبب الفشل
.ألغِ() جديد في 1.4.0: يلغي الوعد ويستدعي ردود الإلغاء (انظر 3.11)
.عند_الغاء(دالة) جديد في 1.4.0: يسجّل دالة تنظيف تُستدعى عند الإلغاء
.مع_مهلة(ثواني) جديد في 1.4.0: يعيد وعداً يفشل بخطأ نوعه "مهلة" عند تجاوز المدة؛ يلغي الوعد الأصلي، لكن الوعد المعاد ليس ملغى
.ملغى جديد في 1.4.0: خاصية هل أُلغي الوعد
غير_متزامن دالة رئيسي() {
  خل وع = وعد()
  حلقة.بعد(0.1, دالة() { وع.حل("وصلت") })    // مؤقت يكمل الوعد بعد 0.1 ثانية
  اطبع(انتظر وع)                             // وصلت
  اطبع(انتظر وعد().حل(2).ثم(س => س * 10))   // 20
}
شغل(رئيسي)

إن فشل وعد داخل انتظر يُرمى خطأه ويمكن مسكه بـ حاول/امسك.

4.5) طرق النصوص

الطريقة الوظيفة
.طول عدد الحروف (خاصية، وكذلك طول(نص))
.قسم(فاصل؟) قائمة أجزاء (بلا فاصل: يقسم عند الفراغات) — "a,b".قسم(",") ← ["a","b"]
.نظف() يحذف الفراغات من الطرفين
.كبير() · .صغير() حروف كبيرة / صغيرة
.يبدأ_ب(ن) · .ينتهي_ب(ن) · .يحتوي(ن) فحوص (تعيد صح/غلط)
.ابدل(قديم, جديد) يستبدل كل الورود
.جزء(من, الى؟) نص جزئي (الى مستثناة، والسالب من النهاية): "abcdef".جزء(1, 4) ← bcd، .جزء(-3) ← def
.ابحث(ن) فهرس أول ورود أو -1
.كرر(ن) يكرر النص (وكذلك "ab" * 3)
.اعكس() عكس النص (تُعيد نصاً جديداً)
.حروف() قائمة الحروف
.سطور() قائمة الأسطر
.املأ_يسار(عرض, حرف) · .املأ_يمين(عرض, حرف) حشو حتى العرض: "5".املأ_يسار(3, "0") ← 005
.نسق(...قيم) نفس نسق والنص هو القالب
.فارغ() هل النص بلا حروف: "".فارغ() ← صح
.موقع(ن, من؟) فهرس أول ورود (حروف وليس بايتات، من يدعم السالب) أو -1 — مثل .ابحث مع بداية بحث
.عد(ن) عدد ورود نص فرعي: "سلامات".عد("ا") ← 2
.خذ(ن) أول ن حروف: "مرحبا".خذ(3) ← مرح
.اترك(ن) كل الحروف بعد أول ن: "مرحبا".اترك(2) ← حبا
.حرف_عند(ف) الحرف عند الفهرس نصاً: "سلام".حرف_عند(1) ← ل
.عنوان_حالة() أول حرف من كل كلمة كبيراً: "hello world".عنوان_حالة() ← Hello World
.كبّر_اول() الحرف الأول كبيراً والباقي كما هو
.نظف_يسار() · .نظف_يمين() يحذف الفراغات من اليسار / اليمين فقط
.هل_حرف_بالحرف() هل كل الحروف حروفاً وأرقاماً (يدعم العربية واللاتينية) والنص غير فارغ
[ف] الحرف عند الفهرس: "abc"[1] ← b

طرق عربية جديدة في 1.4.0:

الطريقة الوظيفة
.ازل_تشكيل() يحذف علامات التشكيل (الفتحة والكسرة والشدّة...) والتطويل: "سَلَــلام".ازل_تشكيل() ← سلام
.طبّع() تطبيع عربي كامل: إزالة التشكيل + توحيد الهمزات والألف والياء والتاء المربوطة: "أهلاً إبراهيم".طبّع() ← اهلا ابراهيم (مفيد للمقارنة والبحث)
.هل_عربي() هل كل حروف النص عربية (مع سماح المسافات والأرقام): "سلام 123".هل_عربي() ← صح، "Hello".هل_عربي() ← غلط
.عد_تشكيل() عدد علامات التشكيل في النص: "مُحَمَّد".عد_تشكيل() ← 4

طرق نصية عامة جديدة في 1.4.0:

الطريقة الوظيفة
.املأ_وسط(عرض, حرف؟) يوسّط النص داخل عرض محدد (الحرف الافتراضي مسافة، التوزيع متوازن): "أب".املأ_وسط(6, "*") ← **أب**
.عد_تطابق(ن) عدد ورود نص فرعي (مثل .عد باسم أوضح): "أأبأ".عد_تطابق("أ") ← 3
.مواقع(ن) مواضع ورود غير متداخلة لنص فرعي بفهرسة Unicode: "أأبأ".مواقع("أ") ← [0، 1، 3]؛ يحسب الإزاحات تراكمياً ولا يعيد مسح البادئة لكل تطابق
.قسم_متعدد(قائمة_فواصل) يقسم عند أقرب فاصل من عدة فواصل: "أ,ب;ج".قسم_متعدد([",", ";"]) ← [أ، ب، ج]

4.6) طرق القوائم

الطريقة الوظيفة
.طول عدد العناصر
.اضف(x) يضيف في النهاية (تعدّل القائمة)
.ادرج(فهرس, x) يدرج قبل الفهرس
.احذف(فهرس) يحذف العنصر عند الفهرس
.اسحب() يحذف آخر عنصر ويعيده
.رتب(مقارن؟) يرتّب القائمة نفسها ويعيدها. المقارن (أ, ب) => رقم (سالب: أ أولاً)
.اعكس() يعكس القائمة نفسها ويعيدها (للنسخة: ق.انسخ().اعكس())
.ادمج(فاصل) يدمج العناصر في نص
.حول(دالة) قائمة جديدة بنتيجة الدالة على كل عنصر
.رشح(دالة) قائمة جديدة بالعناصر التي تعيد فيها الدالة صادقاً
.اطوي(دالة, بداية؟) تجميع: [1,2,3].اطوي((أ, ب) => أ + ب, 0) ← 6
.نفذ(دالة) يستدعي الدالة على كل عنصر
.جد(دالة) أول عنصر تحقق دالته أو عدم
.اي(دالة) · .كل(دالة) هل يحقق بعض العناصر / كلها الدالة
.مجموع() مجموع العناصر الرقمية
.فريد() بلا تكرار
.سطّح() يفرد مستوى واحداً من القوائم المتداخلة
.اول() · .اخر() أول / آخر عنصر
.ابحث(x) فهرس أول ورود أو -1
.يحتوي(x) هل العنصر موجود
.جزء(من, الى؟) قائمة جزئية (مثل النصوص)
.انسخ() نسخة سطحية
.امسح() يفرغ القائمة
.فارغ() هل القائمة بلا عناصر
.ادنى() · .اعلى() أصغر / أكبر عنصر (يقارن ويخطئ على العناصر غير القابلة للمقارنة، ويخطئ على القائمة الفارغة)
.متوسط() متوسط العناصر الرقمية (يخطئ على القائمة الفارغة أو غير الرقمية)
.موقع(x, من؟) فهرس أول ورود بدءاً من من (يدعم السالب) أو -1
.عد(x) عدد ورود العنصر
.خذ(ن) قائمة بأول ن عنصر: [1,2,3].خذ(2) ← [1، 2]
.اترك(ن) قائمة بكل العناصر بعد أول ن
.اقترن(قائمة) يزاوج عنصراً بعنصر: [1,2].اقترن(["أ","ب"]) ← [[1,"أ"]،[2,"ب"]]
.اضف_الكل(قائمة) يضيف كل عناصر القائمة المعطاة (يعدّل القائمة)

طرق القوائم الجديدة في 1.4.0:

الطريقة الوظيفة
.جمع_حسب(دالة_مفتاح) يجمع العناصر في قواميس من مفتاح الدالة إلى قائمة العناصر: [1,2,3,4].جمع_حسب(س => س % 2) ← {0: [2، 4]، 1: [1، 3]}
.عد_حسب(دالة_مفتاح) قاموس من المفتاح إلى عدد وروده: [1,1,2].عد_حسب(س => س) ← {1: 2، 2: 1}
.قسّم_قطع(ن) يقسم القائمة إلى قطع بطول ن (الأخيرة قد تكون أقصر): [1,2,3,4,5].قسّم_قطع(2) ← [[1، 2]،[3، 4]،[5]]
.نوافذ(ن) نوافذ متحركة بطول ن: [1,2,3,4].نوافذ(2) ← [[1، 2]،[2، 3]،[3، 4]]
.فريد_حسب(دالة_مفتاح) بلا تكرار حسب مفتاح الدالة: [1.2, 1.8, 2.5].فريد_حسب(أرضي) ← [1.2، 2.5]
.رتب_حسب(دالة_مفتاح) يرتب القائمة نفسها تصاعدياً بفرز دمجي مستقر (O(n log n) مقارنات)؛ تُحسب دالة المفتاح مرة لكل عنصر
.خذ_طالما(شرط) يأخذ العناصر من البداية ما دام الشرط صادقاً ويتوقف عند أول فشل: [1,2,3,1].خذ_طالما(س => س < 3) ← [1، 2]
.اترك_طالما(شرط) يترك العناصر من البداية ما دام الشرط صادقاً: [1,2,3,1].اترك_طالما(س => س < 3) ← [3، 1]
.سطّح_كلي() يفرد كل مستويات التداخل مهما عمّقت: [1,[2,[3,[4]]]].سطّح_كلي() ← [1، 2، 3، 4]
.فريد_متتال() يحذف التكرارات المتتالية فقط: [1,1,2,2,1].فريد_متتال() ← [1، 2، 1]
.اقترن_مع(قائمة_أخرى, دالة_بوسيطين) يزاوج مع قائمة أخرى ويدمج الزوج بدالة: [1,2].اقترن_مع([10,20], (أ, ب) => أ + ب) ← [11، 22]
.اطوي_يسار(دالة, بداية؟) تجميع من اليسار (مثل .اطوي باسم صريح): [1,2,3].اطوي_يسار((م, س) => م + س, 10) ← 16
.تراكمي(دالة, بداية؟) مجموعات تراكمية (مثل اطوي لكن يعيد كل القيم الوسيطة): [1,2,3].تراكمي((م, س) => م + س, 0) ← [0، 1، 3، 6] — النتيجة تشمل قيمة البداية

دوال حول ورشح وجد واي وكل ونفذ تستدعي الدالة بعنصر واحد.

4.7) طرق القواميس

الطريقة الوظيفة
.طول عدد المفاتيح
.مفاتيح() · .قيم() · .ازواج() قوائم المفاتيح / القيم / أزواج [مفتاح، قيمة] (بترتيب الإدخال)
.احصل(مفتاح, افتراضي؟) القيمة أو الافتراضي (عدم إن لم يُعطَ) — لا يرمي خطأ
.دمج(قاموس) يدمج مفاتيح القاموس الآخر في هذا (تعدّله)
.دمج_جديد(قاموس) مثل .دمج لكن يعيد قاموساً جديداً دون تعديل الأصلي
.احذف(مفتاح) يحذف المفتاح
.انسخ() نسخة سطحية
.امسح() يفرغ القاموس
.فارغ() هل القاموس بلا مفاتيح
.اضبط_افتراضي(مفتاح, قيمة) يضع القيمة إن كان المفتاح غائباً، ويعيد القيمة الحالية (القديمة أو الجديدة) في الحالتين

طرق القواميس الجديدة في 1.4.0:

الطريقة الوظيفة
.حول_قيم(دالة) قاموس جديد بنفس المفاتيح وقيم محولة: {"أ": 1}.حول_قيم(س => س * 10) ← {"أ": 10}
.رشح_مفاتيح(دالة) قاموس جديد بالمفاتيح التي تعيد الدالة عنها صادقاً (الدالة تأخذ المفتاح)
.اعكس_اتجاه() قاموس جديد كل قيمة تصبح مفتاحاً والعكس: {"أ": 1}.اعكس_اتجاه() ← {1: "أ"}
.احصل_عميق(مفتاح1, مفتاح2, ...) يقرأ مساراً متداخلاً من مفاتيح/فهارس (وسائط متعددة وليست قائمة)، ويعيد عدم عند غياب أي حلقة: {"أ": {"ب": 7}}.احصل_عميق("أ", "ب") ← 7
.اضبط_عميق(مسار, قيمة) يضبط قيمة في مسار متداخل (المسار قائمة مفاتيح/فهارس، وينشئ القواميس الوسيطة الغائبة): د.اضبط_عميق(["أ", "ب"], 9) ثم د.احصل_عميق("أ", "ب") ← 9
.ادخل(مفتاح, قيمة) يعيد زوجاً [مفتاح, قيمة] (أداة بناء أزواج للقواميس)

5) المرجع: المكتبات المدمجة (الأصلية)

هذه مكتبات مبنية داخل الملف التنفيذي: تُستورد بـ استورد "الاسم" (ما عدا الخمس المتاحة دائماً: نظام جيسون شبكة سوكت حلقة). كل دالة لها مرادفات في القسم 7. الأرقام بين قوسين: عدد الوسائط (؟ = اختياري).

رياضيات

الدالة الوظيفة
جذر(س) الجذر التربيعي
ارضي(س) · سقف(س) · بتر(س) تقريب لأسفل / لأعلى / حذف الجزء الكسري
قرب(س) تقريب لأقرب صحيح (قرب(2.5) = 3 وقرب(-2.5) = -3)
مطلق(س) القيمة المطلقة
اس(س) e أس س
قوة(س, ص) س أس ص
لوغ(س, اساس؟) لوغاريتم طبيعي (أو بالأساس المعطى): لوغ(8, 2) = 3
لوغ10(س) لوغاريتم عشري
اكبر(...) · اصغر(...) أكبر / أصغر القيم المعطاة (عدد حر من الوسائط)
جيب جتا ظل الدوال المثلثية (بالراديان)
جيب_عكسي جتا_عكسي ظل_عكسي · ظل2(ص, س) معكوساتها، وظل الزاوية بإحداثيين
جيب_زائد(س) · جتا_زائد(س) · ظل_زائد(س) الدوال الزائدية (hyperbolic)
وتر(أ, ب) وتر المثلث: وتر(3, 4) ← 5
جذر_مكعب(س) الجذر التكعيبي (يعمل مع السوالب أيضاً)
لوغ2(س) لوغاريتم بالأساس 2: لوغ2(8) ← 3
باقي(أ, ب) باقي القسمة العائم: باقي(7, 3) ← 1
علامة(س) -1 للسالب و1 للموجب و0 للصفر
الى_درجات(ر) · الى_راديان(د) تحويل بين الراديان والدرجات: الى_درجات(باي) ← 180
بت_و(أ, ب) · بت_او(أ, ب) · بت_خالف(أ, ب) · بت_نفي(أ) عمليات البتات (بت_نفي(0) = -1)
ازح_يسار(أ, ن) · ازح_يمين(أ, ن) إزاحة البتات
باي · اي · لانهاية · لانهاية_سالبة · نان · باي_على_2 · باي_على_4 ثوابت

ضخم (أعداد صحيحة بلا حد)

تُمرَّر الأعداد نصوصاً وتعيد نصوصاً، فلا تفقد دقة: ضخم.جمع("99999999999999999999", "1") ← "100000000000000000000".

الدالة الوظيفة
جمع(أ, ب) · طرح(أ, ب) · ضرب(أ, ب) العمليات الأساسية
قسمة(أ, ب) · باقي(أ, ب) قسمة صحيحة وباقيها (قسمة("100","7") = "14")
قوة(نص, رقم) الأس: ضخم.قوة("2", 100) (الأس رقم عادي)
مضروب(ن) ن! (مضروب(25))
قارن(أ, ب) 1 إن أ>ب و0 متساويان و-1 إن أ<ب
مطلق(أ) القيمة المطلقة: مطلق("-50") ← "50"
نفي(أ) عكس الإشارة: نفي("50") ← "-50"
القاسم_المشترك(أ, ب) أكبر قاسم مشترك: القاسم_المشترك("48", "36") ← "12"
المضاعف_المشترك(أ, ب) أصغر مضاعف مشترك: المضاعف_المشترك("4", "6") ← "12"
رقم(نص) يتحقق أن النص عدداً صحيحاً سليماً ويعيد قيمته رقماً (رقم("0042") = 42) — الأعداد الأضخم من حدود الرقم العادي تفقد دقتها

عشوائي

الدالة الوظيفة
رقم() عشري في [0, 1)
صحيح(أ, ب) صحيح بين أ وب (الطرفان شاملان)
اختر(قائمة) عنصر عشوائي
بين(أ, ب) رقم عشري في [أ, ب)
عينة(قائمة, ن) ن عناصر عشوائية بلا تكرار من القائمة: عينة([1,2,3,4,5], 3)
اخلط(قائمة) يخلط القائمة نفسها ويعيدها
بذرة(ن) يثبّت البذرة لنتائج قابلة للتكرار

زمن

الدالة الوظيفة
الان() الوقت الحالي بالثواني منذ 1970 (عشري)
ساعة() ساعة رتيبة لقياس المدد
نوم(ثواني) يوقف البرنامج (حاجب). في الشيفرة غير المتزامنة استعمل نم
تاريخ(طابع؟, utc؟) قاموس {سنة، شهر، يوم، ساعة، دقيقة، ثانية، اسبوع، يوم_السنة} (اسبوع: 0 = الأحد). بالتوقيت المحلي، أو UTC إن كان الوسيط الثاني صادقاً
من_تاريخ(قاموس, utc؟) الطابع الزمني من قاموس التاريخ
تنسيق(صيغة, طابع؟) تنسيق بصيغة strftime: زمن.تنسيق("%Y-%m-%d", 0)
تحليل(نص, صيغة, utc؟) الطابع الزمني من نص: زمن.تحليل("2024-03-15", "%Y-%m-%d")
الان_مللي() الوقت الحالي بالملي ثانية منذ 1970 — لطوابع زمنية دقيقة (يُعاد نصاً عند تجاوز دقة الرقم لضمان الدقة الكاملة)
منذ(بداية) الثواني المنقضية منذ قراءة سابقة لـزمن.ساعة() (ساعة رتيبة لا تتأثر بتغيير ساعة النظام): خل ب = زمن.ساعة(); ...; زمن.منذ(ب)

للعمل السهل بالتواريخ (إضافة أيام، فروق، تقويم هجري) استعمل مكتبة تواريخ (القسم 6).

نظام

الدالة الوظيفة
بيئة(اسم, افتراضي؟) قيمة متغير بيئة
ضبط_بيئة(اسم, قيمة) يضبط متغير بيئة
حمل_env(مسار؟) يحمّل ملف .env (KEY=value) إلى البيئة ويعيد عدد المتغيرات
منصة() قاموس {نظام، معمارية، jit، فرع، فاصل، نسخة، ضغط_مضمن}
مسار() المجلد الحالي
طرفية() هل المخرجات إلى طرفية (TTY)
اخرج(رمز؟) ينهي البرنامج برمز الخروج
نفذ(امر) يشغّل أمر قشرة ويعيد مخرجاته نصاً
نفذ(امر, خيارات) صيغة موسعة (جديدة في 1.1.0): خيارات {دخل، مهلة، مجلد} ويعيد {رمز، ناتج، خطأ، انتهى_الوقت}
شغل(امر) يشغّل أمراً ويعيد رمز خروجه (المخرجات تظهر مباشرة)
شغل_قائمة([برنامج, وسيط...]) تشغيل بلا قشرة (آمن من حقن الأوامر): يعيد {رمز، ناتج}
عملية(أمر) يشغّل أمر قشرة كعملية فرعية ويعيد {مقبض, pid, دخل, خرج, خطأ} — كل مقبض سوكت قابل للقراءة والمراقبة بحلقة الأحداث (سوكت.استقبل(ع.خرج) لقراءة المخرجات، حلقة.راقب). جديد في 1.4.0: يعمل الآن على ويندوز عبر ناقل عملية داخلي (سابقاً كان يتطلب fork)
انتظر_عملية(pid) ينتظر انتهاء العملية ويعيد رمز خروجها (-1 إن لم توجد)
اقتل(pid) ينهي عملية فرعية
فرع(دالة) جديد في 1.4.0 (ويندوز): يشغّل الدالة في عملية فرعية حقيقية ويعيد {مقبض, pid} — نفس عقد فرع في لينكس. قيد: الدالة تُجمَّد مع متغيراتها العامة، ولا يمكن تجميد كائنات الأصناف؛ لا تعرّف صنف/واجهة في ملف يستعمل فرع (خطأ تعذّر تجميد الدالة للعملية الفرعية)
عامل(دالة) عملية عاملة دائمة بقناة رسائل (أساس مكتبة عمال) — بنفس قيد التجميد على ويندوز
مكتبة_قياسية(اسم) هل توجد مكتبة قياسية بهذا الاسم
بيت_سولان() مسار مجلد المكتبات (SOLAN_HOME)
رموز() · افحص_صياغة(نص) · طبّع(نص) · ارسل_lsp(...) · اقرا_بايتات(...) · اكتب_خام(...) دوال داخلية لأدوات اللغة (خادم LSP والمنسّق)

نفذ بالصيغة الموسعة (جديدة في 1.1.0):

استورد "نظام"
خل ر = نظام.نفذ("برنامج", {دخل: "نص الإدخال", مهلة: 5, مجلد: "C:\\عمل"})
اطبع(ر.رمز, ر.ناتج, ر.خطأ, ر.انتهى_الوقت)

دخل يُمرَّر إلى الإدخال القياسي للبرنامج، مهلة بالثواني (عند تجاوزها يُنهى البرنامج وتكون رمز = -2 وانتهى_الوقت = صح)، ومجلد مجلد العمل. بلا خيارات يبقى السلوك القديم (نص المخرجات فقط).

ملفات

كل مسار يخضع لنظام الصلاحيات (القسم 8).

الدالة الوظيفة
اقرا(مسار) محتوى الملف نصاً
سطور(مسار) الملف كقائمة أسطر
اكتب(مسار, نص) يكتب (يستبدل الملف)
الحق(مسار, نص) يضيف إلى نهاية الملف
موجود(مسار) · هل_مجلد(مسار) · هل_رابط(مسار) فحوص
حجم(مسار) الحجم بالبايت
قائمة(مجلد) أسماء محتويات المجلد
انشئ_مجلد(مسار) · انشئ_مجلدات(مسار) ينشئ مجلداً / سلسلة مجلدات متداخلة
انسخ(من, الى) · انقل(من, الى) نسخ ونقل
احذف(مسار) · احذف_مجلد(مسار) · احذف_شجرة(مسار) حذف ملف / مجلد فارغ / مجلد بكل محتوياته
مسار_مطلق(مسار) المسار المطلق
مسار_البيت() مجلد المستخدم
هل_ملف(مسار) هل المسار ملفاً عادياً (لا مجلداً ولا رابطاً)
معلومات(مسار) قاموس معلومات الملف: {حجم، ملف، مجلد، تعديل، تغيير، وصول} (الأزمنة طوابع Unix بالثواني، ويعيد عدم عند عدم وجود المسار)

تعيد معظمها صح عند النجاح، وترمي خطأً عربياً عند الفشل (مثلاً تعذّرت قراءة الملف '...').

جيسون

الدالة الوظيفة
ترميز(قيمة, مسافة؟) قيمة سولان ← نص JSON (مسافة = عدد مسافات الإزاحة لنص منسّق)
فك(نص) نص JSON ← قيمة سولان (null ← عدم)
هل_صالح(نص) هل النص JSON سليماً (صح/غلط) دون إنتاج القيمة — أسرع من فك للفحص فقط

نمط (التعابير النمطية)

محرك مدمج يدعم المجموعات والمجموعات المسمّاة و\d \w \s والحدود والنظرات الأمامية، وبلا مكتبة خارجية. كل دالة تأخذ (نمط, نص, خيارات؟).

الدالة الوظيفة
ابحث(نمط, نص) أول تطابق: قاموس {نص، بداية، نهاية، مجموعات، مسميات} أو عدم. مجموعات قائمة نصوص المجموعات، ومسميات قاموس المجموعات المسمّاة (?<اسم>...)
هل(نمط, نص) هل يوجد تطابق في أي موضع
مطابق_كامل(نمط, نص) هل يطابق النص كله
كل(نمط, نص) قائمة بكل التطابقات (كل عنصر قاموس مثل نتيجة ابحث)
قسم(نمط, نص) يقسم النص عند التطابقات
ابدل(نمط, نص, بديل, خيارات؟) استبدال (يدعم $1 $2 للمجموعات)
مجموعات(نمط, خيارات؟) قائمة أسماء مجموعات الالتقاط المسمّاة في النمط: مجموعات("(?<سنة>\\d{4})-(?<شهر>\\d{2})") ← ["سنة"، "شهر"]

الخيارات قاموس: {"تجاهل_الحالة": صح} و"تطبيع" (يتجاهل الهمزات والتشكيل) و"متعدد" (^/$ لكل سطر) و"نقطة_سطر" (النقطة تطابق السطر الجديد). مثال: نمط.هل("HELLO", "hello", {"تجاهل_الحالة": صح}) ← صح.

استورد "نمط"
خل م = نمط.ابحث("(\\d+)-(\\d+)", "هاتف 555-1234")
اطبع(م.نص)                                         // 555-1234
اطبع(نمط.ابدل("(\\w+)@(\\w+)", "ali@site", "$2:$1")) // site:ali

(داخل نص سولان يُكتب الشرطة المائلة مضاعفة: "\\d".)

تشفير

الدالة الوظيفة
sha256(نص) · sha1(نص) بصمة ست عشرية (sha256("abc") ← ba7816bf...15ad)
sha512(نص) بصمة SHA-512 ست عشرية (128 خانة)
hmac_sha256(مفتاح, رسالة) · hmac_sha1(مفتاح, رسالة) توقيع HMAC
base64(نص) · base64_قياسي(نص) · فك_base64(نص) ترميز وفك Base64 القياسي
base64_رابط(نص) Base64 آمن للروابط (بلا حشو =، بـ - و_)
hex(نص) · فك_hex(نص) ترميز وفك ست عشري
crc32(نص) بصمة CRC32 عدداً (المستعمل في ملفات zip وفحص سلامة البيانات)
pbkdf2_sha256(كلمة_السر, ملح, تكرارات, طول؟) اشتقاق مفتاح PBKDF2-HMAC-SHA256 نص ست عشري: pbkdf2_sha256("سر", "ملح", 100000) (الطول بالبايت، افتراضياً 32، بحدود 1-4096، والتكرارات 1-10000000). لتخزين كلمات السر: خزّن الملح والتكرارات مع الناتج وقارن الناتج عند الدخول. جديد في 1.4.0: إصلاح خلل الوسيط الرابع (كان يُقرأ خطأً فأعطى ناتجاً خاطئاً عند تحديد الطول — الآن يقبل رقماً أو نصاً) وتحسين بوسطية HMAC ثابتة تُبنى مرة واحدة؛ كل تكرار يحتاج كتلتَي SHA-256 بدل إعادة بناء HMAC كاملة (حتى أربع كتل وتخصيصات ذاكرة)
عشوائي_بايتات(ن) ن بايتات عشوائية آمنة تشفيرياً

X25519 (تبادل مفاتيح Diffie-Hellman — RFC 7748)

كل المداخل والمخارج ست عشرية (64 خانة = 32 بايت). التقييد (clamping) يتم تلقائياً وفق RFC.

الدالة الوظيفة
x25519_سر() مفتاح سر عشوائي (يقبل وسيطاً اختيارياً: بذرة hex للتجارب)
x25519_عام(سر) المفتاح العام = X25519(سر, 9)
x25519_مشترك(سر, عام_الطرف_الآخر) السر المشترك X25519(سر, عام)
استورد "تشفير"
خل سري = تشفير.x25519_سر()
اطبع("عامي: " + تشفير.x25519_عام(سري))
// السر المشترك متطابق عند الطرفين:
// تشفير.x25519_مشترك(سري, عام_الطرف_الآخر) == تشفير.x25519_مشترك(سره, عامي)

Ed25519 (توقيع رقمي — RFC 8032)

المفاتيح 64 خانة hex، والتوقيع 128 خانة hex (نقطة R + عدد S). التحقق يرفض S ≥ L ويجري الفحص [S]B = R + [k]A وفق RFC.

الدالة الوظيفة
ed25519_سر() بذرة سر عشوائية (يقبل وسيطاً اختيارياً: بذرة hex)
ed25519_عام(سر) المفتاح العام [a]B بعد توسيع البذرة (SHA-512 + تقييد)
ed25519_وقّع(سر, رسالة) توقيع الرسالة (الرسالة نص بايتات خام)
ed25519_تحقق(عام, رسالة, توقيع) صح/غلط
استورد "تشفير"
خل سري = تشفير.ed25519_سر()
خل عامي = تشفير.ed25519_عام(سري)
خل تو = تشفير.ed25519_وقّع(سري, "مرحبا")
اطبع(تشفير.ed25519_تحقق(عامي, "مرحبا", تو))   // صح
اطبع(تشفير.ed25519_تحقق(عامي, "مرحبا!", تو))  // غلط

التنفيذ خالص من الصفر (بلا OpenSSL): حقل 2^255-19 بأطراف 64-بت أساس 2^16، SHA-512 مدمجة، ثوابت مشتقة وقت التشغيل، ومطابق لمتجهات RFC 7748 وRFC 8032 الرسمية.

ضغط

الدالة الوظيفة
gzip(نص) · gunzip(بيانات) ضغط وفك بصيغة gzip
zlib(نص) · فك(بيانات) ضغط zlib وفك أي من الصيغتين
فك_zlib(بيانات) فك zlib حصراً (عندما تعرف الصيغة، بينما فك تجرب gzip ثم zlib)
خام(نص) ضغط DEFLATE خام (بلا ترويسة zlib ولا المجموع) — صيغة جسم ملف zip وHTTP deflate
فك_خام(بيانات) فك DEFLATE الخام

الضغط مضمَّن في اللغة ولا يحتاج libz.

شبكة (HTTP)

الدالة الوظيفة
جلب(رابط, خيارات؟) طلب HTTP/HTTPS متزامن (حاجب). يعيد {حالة، جسم، رؤوس، ناجح، رابط}
جلب_متدفق(رابط, callback, خيارات؟) طلب HTTP/HTTPS متزامن يمرّر كل جزء من جسم الرد إلى callback فور وصوله، دون انتظار اكتمال الجسم
خادم(منفذ, معالج, خيارات؟) خادم HTTP (حاجب)
خادم_حلقة(منفذ, معالج, خيارات؟) خادم HTTP على حلقة الأحداث (لا يحجب؛ المعالج قد يكون غير_متزامن)
ترميز_رابط(نص) · فك_رابط(نص) ترميز وفك النص داخل الروابط (%XX)
حلل_رابط(رابط) يحلل رابطاً إلى قاموس: {المخطط، المضيف، المنفذ، المسار، مؤمن} (مؤمن = صح للـhttps)، ويعيد عدم إن كان الرابط غير صالح
اقرا_طلب(...) · اكتب_رد(...) مستوى منخفض لبناء خوادم مخصصة فوق السوكت

خيارات جلب: طريقة ("GET" افتراضياً)، رؤوس (قاموس)، جسم (نص، أو قاموس/قائمة فيُرسَل JSON تلقائياً)، مهلة (ثواني)، تحقق (غلط يعطّل فحص شهادة TLS، أو مسار ملف حزمة CA بديل)، تحويلات (عدد التحويلات المسموحة)، نموذج (قاموس لإرسال multipart/form-data)، نموذج_رابط (قاموس بصيغة x-www-form-urlencoded)، رؤوس_فقط (صح = طلب HEAD يعيد الرؤوس بلا جسم)، بروكسي (انظر أدناه).

عميل TLS الخالص (مضمّن بلا أي مكتبة خارجية)

شبكة.جلب على HTTPS يعمل عبر عميل TLS خالص مضمّن في الملف التنفيذي مكتوب بالكامل داخل المشروع بلا أي مكتبة خارجية:

العنصر التفصيل
الإصدارات TLS 1.3 (TLS_AES_128_GCM_SHA256 وTLS_CHACHA20_POLY1305_SHA256) وTLS 1.2 (RSA ثابت 0x003C/0x003D + ECDHE-RSA-AES128-SHA256 مع Extended Master Secret)
المنحنيات X25519 وP-256 وP-384
الشهادات تحقق كامل: سلسلة X.509 (RSA وECDSA P-256/P-384)، الصلاحية الزمنية، اسم المضيف، والتوقيعات (RSA-PKCS1 وRSA-PSS وECDSA)؛ الجذر الموثوق من شهادات النظام أو SOLAN_CA_BUNDLE أو خيار تحقق
الحدود HTTP/1.1 فقط (لا HTTP/2)، ولا session resumption ولا OCSP/CRL ولا mTLS

بروكسي

الخيار الوظيفة
بروكسي توجيه الاتصال عبر "socks5://مضيف:منفذ" أو "http://مضيف:منفذ" (CONNECT)، ويدعم user:pass@ — يعمل على HTTP وHTTPS وwss عبر العميل الخالص
استورد "شبكة"
خل ق = شبكة.جلب("https://example.com", {بروكسي: "socks5://127.0.0.1:9050"})
خل رؤوس = شبكة.جلب("https://example.com", {رؤوس_فقط: صح})
  • حزمة شهادات CA احتياطية مدمجة: إن لم توجد شهادات النظام تُستعمل الحزمة المدمجة فيعمل HTTPS فوراً.

جلب_متدفق: قراءة جسم الرد أثناء وصوله

جلب_متدفق(رابط, callback, خيارات؟) واجهة أصلية في محرك Solan. تقرأ الجسم تدريجياً وتستدعي callback(جزء) مع كل جزء وصل من اتصال HTTP، قبل اكتمال الاستجابة. تدعم أجسام Content-Length وTransfer-Encoding: chunked والردود المنتهية بإغلاق الاتصال؛ وتعيد في النهاية قاموس الاستجابة المعتاد {حالة، جسم، رؤوس، ناجح، رابط}. اتبع التحويلات أولاً، ولا يُمرر جسم رد التحويل إلى callback.

استورد "شبكة"

خل الرد = شبكة.جلب_متدفق("https://example.com/events", دالة(جزء) {
  // تُستدعى هذه الدالة أثناء وصول bytes، لا بعد تنزيل الرد كاملاً.
  اطبع(جزء)
}, {
  "رؤوس": {"accept": "text/event-stream"},
  "مهلة": 60,
  "اجمع_الجسم": غلط
})
اذا ليس الرد["ناجح"] { اطبع("HTTP " + نص(الرد["حالة"])) }

الـ callback يستقبل أجزاء نقل خاماً، لا أحداث SSE محلّلة؛ فقد ينقسم حدث SSE أو محرف UTF-8 بين جزأين، وقد يحتوي جزء واحد عدة أحداث. اجمع الأجزاء في مخزن التطبيق ثم حلّل حدود الأحداث (مثل \n\n في SSE) وفك النص بعد إعادة جمع البايتات. الخيار اجمع_الجسم افتراضه غلط لتفادي تخزين الرد كله؛ عند ضبطه إلى صح يتضمن الرد["جسم"] نسخة الجسم الكاملة أيضاً. حتى مع التجميع، يبقى callback تدريجياً.

الدالة متزامنة: استدعاء جلب_متدفق نفسه ينتظر نهاية الرد، بينما callback يُنفَّذ على أجزاء وصوله؛ ليست واجهة Promise ولا تجعل استدعاء HTTP غير حاجب. تستخدم الطلب Accept-Encoding: identity افتراضياً لتفادي ضغط الجسم قبل callback؛ إذا حدّدت accept-encoding بنفسك، فمسؤولية فك الضغط على التطبيق. callback يستقبل الجسم حتى مع حالات HTTP غير الناجحة؛ افحص الرد["ناجح"] بعد اكتمال النقل. المهلة أو فشل القراءة بعد بيانات جزئية يرمي خطأ ولا يعيد استجابة جزئية كأنها مكتملة. رمي callback يُغلق الاتصال ويمرّر الاستثناء إلى المستدعي.

معالج الخادم يستقبل طلب بالحقول: طريقة مسار استعلام (قاموس) رؤوس جسم عنوان (عنوان العميل). وما يعيده يتحدد هكذا:

  • نص ← استجابة HTML.
  • قاموس فيه جسم وحالة ورؤوس (كلها اختيارية): حالة رمز HTTP (200 افتراضياً)، وجسم نص أو قاموس/قائمة (فيُرسَل JSON).

خيارات خادم: عنوان (للاستماع)، اقصى_طلبات، وعمليات (عدد العمليات العاملة). خادم TLS غير مدعوم — تمرير شهادة/مفتاح يرمي خطأً واضحاً.

سوكت (TCP وUDP)

الدالة الوظيفة
استمع(منفذ, خيارات؟) يفتح مقبض استماع
اقبل(مقبض) يقبل اتصالاً: يعيد [مقبض_العميل, عنوانه]
اتصل(مضيف, منفذ, خيارات؟) يتصل بخادم ويعيد مقبضاً (الخيارات: تشفير = صح لمصافحة TLS عبر العميل الخالص، تحقق، مهلة)
ارسل(مقبض, نص) يرسل بيانات
استقبل(مقبض, حد؟) يقرأ ما وصل (حتى حد بايت) أو عدم عند الإغلاق
بالضبط(مقبض, ن) يقرأ ن بايت بالضبط
سطر(مقبض) يقرأ سطراً (حتى \n) أو عدم عند الإغلاق
مهلة(مقبض, ثواني) مهلة القراءة
غير_حاجز(مقبض, قيمة؟) تفعيل الوضع غير الحاجز
انتظر(مقابض, مهلة؟) ينتظر جاهزية أحد المقابض (select)
عنوان(اسم) يحوّل اسم مضيف إلى عنوان IP: سوكت.عنوان("localhost") ← 127.0.0.1
udp(منفذ؟) · ارسل_الى(مقبض, مضيف, منفذ, بيانات) · استقبل_من(مقبض) UDP
اغلق(مقبض) يغلق

ويبسوكت

الدالة الوظيفة
اتصل(رابط, خيارات؟) يتصل بـ ws:// أو wss:// ويعيد قناة (الخيارات: تحقق رؤوس مهلة)
ترقية(...) ترقية طلب HTTP وارد إلى ويبسوكت (لبناء خادم)
ارسل(قناة, رسالة, نوع؟) يرسل رسالة
استقبل(قناة, مهلة؟) يستقبل رسالة، أو عدم عند إغلاق الاتصال
نبض(قناة) يرسل ping للإبقاء على الاتصال
اغلق(قناة) يغلق القناة

حلقة (حلقة الأحداث)

حلقة واحدة تدير المؤقتات والمقابض والوعود وبلا خيوط.

الدالة الوظيفة
بعد(ثواني, دالة) ينفّذ الدالة مرة بعد المدة (يعيد مؤقتاً)
كل(ثواني, دالة) ينفّذها كل مدة (يعيد مؤقتاً)
الغ(مؤقت) يلغي مؤقتاً
راقب(مقبض, دالة) يستدعي الدالة كلما صار المقبض (سوكت/قناة) جاهزاً للقراءة
الغ_مراقبة(مقبض) يوقف المراقبة
خطوة() دورة واحدة من الحلقة
شغل() يشغّل الحلقة حتى لا يبقى عمل أو يُستدعى اوقف
اوقف() يوقف الحلقة
استورد "حلقة"
خل م = حلقة.كل(0.1, دالة() { اكتب(".") })
حلقة.بعد(0.35, دالة() { حلقة.الغ(م); اطبع(" انتهى"); حلقة.اوقف() })
حلقة.شغل()

أرشيف (ZIP)

إنشاء وقراءة ملفات zip بلا أي مكتبة خارجية.

الدالة الوظيفة
افتح_كتابة(مسار) ينشئ أرشيفاً جديداً ويعيد مقبضاً للكتابة
اضف(مقبض, اسم, محتوى) يضيف محتوى نصياً باسم معين داخل الأرشيف
اضف_ملف(مقبض, مسار, اسم_داخل؟) يضيف ملفاً من القرص (الاسم الافتراضي: اسم الملف بلا مجلداته)
اضف_مجلد(مقبض, مسار, بادئة؟) يضيف مجلداً بكل محتوياته
افتح_قراءة(مسار) يفتح أرشيفاً موجوداً ويعيد مقبضاً للقراءة
محتويات(مقبض) قائمة أسماء ملفات الأرشيف
يوجد(مقبض, اسم) هل يوجد ملف بهذا الاسم داخل الأرشيف
اقرأ(مقبض, اسم) محتوى ملف من الأرشيف نصاً
استخرج(مقبض, اسم, الى؟) يستخرج ملفاً واحداً إلى مسار (افتراضياً المجلد الحالي بنفس الاسم)
فك_الكل(مقبض, الى؟) يستخرج كل الملفات (افتراضياً إلى المجلد الحالي)
اغلق(مقبض) يحفظ ويغلق الأرشيف
استورد "أرشيف"
خل ض = أرشيف.افتح_كتابة("نسخة.zip")
أرشيف.اضف(ض, "ملاحظات.txt", "مرحبا")
أرشيف.اضف_ملف(ض, "بيانات.json")
أرشيف.اغلق(ض)

خل ق = أرشيف.افتح_قراءة("نسخة.zip")
اطبع(أرشيف.محتويات(ق))
اطبع(أرشيف.اقرأ(ق, "ملاحظات.txt"))
أرشيف.اغلق(ق)

قاعدة_سريعة (مخزن مفاتيح-قيم)

مخزن مفاتيح-قيم مكتوب بالكامل داخل المشروع (بلا أي مكتبة خارجية): يفتح ملفاً على القرص ويحفظ تلقائياً بعد كل عملية. القيم المدعومة: عدم وصح/غلط ورقم ونص (وللبيانات المعقدة استعمل جيسون.ترميز قبل الحفظ وجيسون.فك بعد القراءة). المفاتيح نصوص حتى 1 ميغابايت، والقيم حتى 256 ميغابايت، ويمكن فتح 64 مخزناً في الوقت نفسه.

الدالة الوظيفة
افتح(مسار) يفتح مخزناً (ينشئه إن لم يوجد) ويعيد مقبضاً
ضع(مقبض, مفتاح, قيمة) يحفظ قيمة تحت مفتاحاً (ينشئ أو يستبدل)
احصل(مقبض, مفتاح, افتراضي؟) يقرأ قيمة المفتاح (يعيد عدم أو القيمة الافتراضية إن غاب)
يوجد(مقبض, مفتاح) صح إن وُجد المفتاح
احذف(مقبض, مفتاح) يحذف مفتاحاً
زد(مقبض, مفتاح, مقدار؟) يزيد قيمة رقمية بمقدار (الافتراضي 1) ويعيد القيمة الجديدة؛ يرمي خطأً إن لم تكن القيمة رقماً
مفاتيح(مقبض) قائمة كل المفاتيح
عدد(مقبض) عدد المفاتيح الحية
احفظ(مقبض) يضمن كتابة كل التغييرات على القرص فوراً
اضغط(مقبض) يدعم المخزن: يزيل السجلات القديمة ويصغّر الملف (يحدث تلقائياً أيضاً عند الحاجة)
اغلق(مقبض) يحفظ ويغلق المخزن
استورد "قاعدة_سريعة"
خل خ = قاعدة_سريعة.افتح("بيانات.kv")
قاعدة_سريعة.ضع(خ, "اسم", "سولان")
قاعدة_سريعة.زد(خ, "زيارات")
اطبع("${قاعدة_سريعة.احصل(خ، "اسم")} — زيارات: ${قاعدة_سريعة.احصل(خ، "زيارات")}")
قاعدة_سريعة.ضع(خ, "اعدادات", جيسون.ترميز({"وضع": "ليلي"}))
خل ا = جيسون.فك(قاعدة_سريعة.احصل(خ, "اعدادات"))
اطبع(ا.وضع)
قاعدة_سريعة.اغلق(خ)

ffi (استدعاء مكتبات C)

انظر القسم 11.


6) المرجع: المكتبات القياسية (المكتوبة بسولان)

هذه مكتبات مكتوبة بسولان نفسها ومضمَّنة داخل الملف التنفيذي (لا تحتاج تثبيتاً). تُستورد بـ استورد "الاسم" ثم الاسم.دالة(...). القيم الظاهرة في الوسائط بعد = هي الافتراضية. وللتحقق من وجود مكتبة قياسية: نظام.مكتبة_قياسية("اسم").

المكتبة الغرض
نصوص معالجة النصوص والعربية
مسارات التعامل مع مسارات الملفات
مجموعات هياكل بيانات ودوال للقوائم
عرض تنسيق الأرقام والأحجام والمدد
تواريخ التواريخ والتقويم الهجري
جداول CSV وTSV
قوالب قوالب نصوص/HTML
مخطط التحقق من شكل البيانات
نتيجة نتيجة وخيار للتعامل مع الأخطاء
ألوان ألوان الطرفية والأطر وأشرطة التقدم
اختبار إطار اختبارات للمستخدمين
سجل تسجيل الأحداث
ذاكرة ذاكرة مؤقتة (cache)
بث مرسل أحداث (event emitter)
عمال عمليات عاملة وتوازي
وسائط قراءة وسائط سطر الأوامر
حزم · خادم_اللغة داخلية: تنفّذ أوامر الحزم وخادم LSP

نصوص

الدالة الوظيفة
هل_فارغ(س) نص فارغ أو فراغات فقط
نظف_يسار(س) · نظف_يمين(س) حذف الفراغات من جهة واحدة
ازل_بادئة(س, ب) · ازل_لاحقة(س, ل) حذف بادئة/لاحقة إن وُجدت
يبدأ_باحد(س, قائمة) · ينتهي_باحد(س, قائمة) هل يبدأ/ينتهي بأحد النصوص
اقتطع(س, حد, لاحقة="…") يقص النص عند الحد ويضيف اللاحقة
كلمات(س) · عدد_كلمات(س) قائمة الكلمات وعددها
عد(س, ج) عدد مرات ورود الجزء ج
املأ_يسار(س, ع, ح) · املأ_يمين(س, ع, ح) · وسّط(س, ع, ح) حشو حتى العرض ع بالحرف ح
صفر_بادئ(رقم, ع) صفر_بادئ(7, 3) ← 007
لف(س, عرض) التفاف الأسطر عند عرض معين
ازل_التشكيل(س) · طبّع_عربي(س) حذف التشكيل / توحيد الهمزات والتاء المربوطة
هل_عربي(س) · هل_ارقام(س) فحوص
الى_هندية(س) · الى_غربية(س) تحويل الأرقام داخل النص
مفكك(س) يفكك اسماً إلى كلماته: مفكك("HelloWorld foo") ← ["hello"، "world"، "foo"]
ثعباني(س) · وصلات(س) · جمل(س) · باسكال(س) · عنوان(س) تحويل صيغ الأسماء: ثعباني("helloWorld") ← hello_world، وصلات("Hello World") ← hello-world، جمل("hello world") ← helloWorld (camelCase)، باسكال("hello_world") ← HelloWorld، عنوان("hello world") ← Hello World
وصلة_رابط(س) نص صالح للروابط (slug)
مسافة(أ, ب) مسافة التحرير (Levenshtein): مسافة("kitten","sitting") ← 3
تشابه(أ, ب) نسبة تشابه بين 0 و1
اقرب(س, خيارات, حد=0.6) أقرب خيار للنص (للاقتراحات)
رمز_عشوائي(ط=16, ابجدية=...) رمز عشوائي بطول ط
جديد() باني نصوص بفعالية: .اضف(س) .سطر(س) .امسح() .نص() .طول()

مسارات

الدالة الوظيفة
ضم(...اجزاء) يضم الأجزاء بفاصل واحد: ضم("/a", "b") ← /a/b (بلا تطبيع، فللتطبيع استعمل طبّع_المسار)
الاسم(م) · المجلد(م) · الامتداد(م) · بلا_امتداد(م) أجزاء المسار
هل_مطلق(م) · مطلق(م) · البيت() فحص المطلق، وتحويله لمطلق، ومجلد المستخدم
طبّع_المسار(م) يحل .. و.: طبّع_المسار("/a/b/../c/./d") ← /a/c/d
حلل(م) قاموس {مجلد، اسم، امتداد، جذع}: حلل("/a/b.txt") ← {"مجلد": "/a"، "اسم": "b.txt"، "امتداد": ".txt"، "جذع": "b"}
مقاطع(م) قائمة مقاطع المسار
استبدل_امتداد(م, ام) · اضف_امتداد(م, ام) تعديل الامتداد
نسبي(من, الى) المسار النسبي بين مسارين
هل_داخل(م, جذر) هل المسار داخل المجلد الجذر (للأمان)
مطابق(م, نمط_glob) مطابقة نمط glob (*.سو)
ابحث(مجلد, نمط_glob="*", تكراري=صح) يبحث عن الملفات المطابقة
مجلد_مؤقت(بادئة="solan_") ينشئ مجلداً مؤقتاً

مجموعات

العنصر الوظيفة
مجموعة_من(عناصر) مجموعة فريدة: .اضف .احذف .يحتوي .حجم .فارغة .قيم .الى_قائمة .امسح .لكل_عنصر .حول .رشح .اتحاد .تقاطع .فرق .فرق_متماثل .هل_جزء_من .يساوي — .حجم و.فارغة خاصيتان
طابور() FIFO: .ادفع .اسحب .انظر .حجم .فارغ .الى_قائمة .امسح — .حجم و.فارغ خاصيتان
مكدس() LIFO: .ادفع .اسحب .انظر .حجم .فارغ .الى_قائمة .امسح — .حجم و.فارغ خاصيتان
ثنائي_الطرف() .اضف_خلف .اضف_امام .ازل_امام .ازل_خلف .امام .خلف .حجم .فارغ .الى_قائمة — .حجم و.فارغ خاصيتان
كومة() طابور أولوية: .ادفع .اسحب .انظر .حجم .فارغة — .حجم و.فارغة خاصيتان
عداد(قائمة) قاموس: كل عنصر ← عدد ورودة: عداد(["أ","ب","أ"]) ← {"أ": 2، "ب": 1}
الاكثر_شيوعا(قائمة, ن=3) أكثر العناصر ورودا
فريد(قائمة) · سطّح(قائمة, عمق=1) · مجموع(قائمة) قوائم
دفعات(قائمة, حجم) دفعات([1,2,3,4,5], 2) ← [[1،2]،[3،4]،[5]]
نوافذ(قائمة, حجم) نوافذ منزلقة: نوافذ([1,2,3,4], 2)
ازواج(أ, ب) يزاوج عناصر قائمتين
جمّع(قائمة, ف) يجمّع حسب نتيجة الدالة (قاموس)
قسّم_حسب(قائمة, شرط) [[المحققة]، [غير المحققة]]: قسّم_حسب([1,2,3,4], س => س > 2) ← [[3،4]،[1،2]]
خلط(قائمة) · عينة(قائمة, ن=1) خلط وعينة عشوائية
اكبر(قائمة, ف) · اصغر(قائمة, ف) أكبر/أصغر عنصر (حسب دالة اختيارية)
ادمج_قواميس(...ق) · عكس_قاموس(م) دمج قواميس، وعكس المفاتيح والقيم
اتحاد(أ, ب) · تقاطع(أ, ب) · فرق_مجموعات(أ, ب) عمليات المجموعات على القوائم مباشرة (تعيد قائمة بلا تكرار): اتحاد([1,2,3], [3,4]) ← [1،2،3،4]

عرض

الدالة الوظيفة
ارقام_مفصولة(ن, فاصل=",", عشري) ارقام_مفصولة(1234567.891) ← 1,234,567.891
حجم_ملف(بايت, عشري=1, عربي=غلط) حجم_ملف(1536) ← 1.5 KB
نسبة(ق, عشري=1) نسبة(0.256) ← 25.6%
عملة(ق, رمز="", عشري=2) عملة(1234.5, "$") ← 1,234.50 $
عدد_معدود(ن, مفرد, مثنى, جمع, كثير) صيغة العدد العربية الصحيحة: عدد_معدود(1, "كتاب", "كتابان", "كتب") ← كتاب، 2 ← كتابان، 5 ← 5 كتب
مدة(ثواني, حد=2) · مدة_قصيرة(ثواني) مدة(3725) ← ساعة و دقيقتان، ومدة_قصيرة(3725) ← 1h 2m 5s
عدد_بالحروف(ن) العدد كتابةً بالحروف: 125 ← «مئة وخمسة وعشرون»

تواريخ

التاريخ طابع زمني (ثواني). الوسيط utc افتراضه صح.

الدالة الوظيفة
الان() · انشئ(سنة, شهر=1, يوم=1, ساعة=0, دقيقة=0, ثانية=0) الآن، أو تاريخ محدد
اجزاء(ت) قاموس الأجزاء (سنة، شهر، ...)
اضف(ت, م) · اطرح(ت, م) إضافة/طرح مدة ممثلة بقاموس: تواريخ.اضف(ت, {"ايام": 1})
فرق(أ, ب, وحدة="ثواني") الفرق بين تاريخين بوحدة ("ايام" ...)
بداية_اليوم نهاية_اليوم بداية_الشهر نهاية_الشهر بداية_السنة بداية_الاسبوع(ت, اول_يوم=6) حدود الفترات (الأسبوع يبدأ السبت افتراضياً)
هل_كبيسة(س) · ايام_الشهر(س, ش) · هل_نفس_اليوم(أ, ب) فحوص وحسابات
اسم_اليوم(ت) · اسم_الشهر(ت, نمط_اسماء="ميلادي") الأسماء بالعربية (الأنماط: ميلادي، شامي، هجري)
تنسيق(ت, صيغة) تنسيق strftime
الى_iso(ت) · حلل_iso(نص) · حلل(نص, صيغة) ISO 8601 وتحليل النصوص
قبل(ت, الان_) «قبل 3 ساعات» بالعربية
الى_هجري(ت) · من_هجري(س, ش, د) · نص_هجري(ت) التقويم الهجري
اسماء_الايام · اسماء_الاشهر · اسماء_الاشهر_شامية · اسماء_الاشهر_هجرية قوائم الأسماء

جداول (CSV وTSV)

الدالة الوظيفة
حلل(نص, فاصل=",") CSV ← قائمة صفوف (قوائم)
حلل_رؤوس(نص, فاصل=",") الصف الأول رؤوس ← قائمة قواميس
حول_انواع(قواميس) يحوّل النصوص الرقمية إلى أرقام
كتب(صفوف, فاصل) · كتب_قواميس(قواميس, رؤوس, فاصل) قائمة ← نص CSV
اقرا(مسار, فاصل) · احفظ(مسار, بيانات, فاصل) قراءة/كتابة ملف CSV
كشف_فاصل(نص) يخمّن الفاصل
حلل_tsv(نص) · كتب_tsv(قواميس) TSV
اختر(قواميس, اعمدة) · عمود(قواميس, عمود) · اعمدة(قواميس) اختيار أعمدة
رتب_حسب(قواميس, عمود, تنازلي=غلط) · جمّع_حسب · فريد_حسب ترتيب وتجميع
مجموع · متوسط · اعلى · ادنى (قواميس, عمود) إحصاءات على عمود
اعرض(بيانات, رؤوس, حد=40) جدول منسّق للطرفية

قوالب

صياغة شبيهة بـ Mustache:

الصياغة المعنى
{{اسم}} قيمة متغير (يدعم {{ع.اسم}} و{{قائمة[0]}})
{{{اسم}}} قيمة بلا هروب HTML
{{اسم | مرشح}} مرشح: كبير صغير عنوان نظف طول ادمج:"-" افتراضي:"س" اقتطع ارقام حجم نسبة مدة هرب جيسون …
{{#اذا شرط}}…{{والا}}…{{/اذا}} شرط
{{#لكل ع في عناصر}}…{{والا}}…{{/لكل}} تكرار (والا إن كانت القائمة فارغة)
الدالة الوظيفة
ارسم(نموذج, بيانات, هرب=غلط) يملأ القالب
ارسم_html(نموذج, بيانات) مثل ارسم مع هروب HTML لـ {{...}} تلقائياً
صرّف(نموذج) يترجم القالب مرة واحدة لإعادة استعماله
هرب_html(س) يهرب النص
استورد "قوالب"
اطبع(قوالب.ارسم("مرحبا {{اسم | كبير}}! {{#لكل ع في عناصر}}[{{ع}}]{{/لكل}}", {"اسم": "ali", "عناصر": [1, 2]}))
// مرحبا ALI! [1][2]

مخطط (التحقق من البيانات)

الدالة الوظيفة
سلسلة(خيارات) · عدد(خيارات) · منطقي(خيارات) · قائمة_من(عناصر, خيارات) · كائن(حقول, خيارات) · اي(خيارات) بناء قواعد
صالح(بيانات, قاعدة) صح/غلط
افحص(بيانات, قاعدة) يعيد {صالح، اخطاء، قيمة} (كل خطأ {مسار، رسالة})
افتح(بيانات, قاعدة) يعيد البيانات إن صحّت، وإلا يرمي قاموساً {رسالة، اخطاء}
استورد "مخطط"
خل قاعدة = مخطط.كائن({"اسم": مخطط.سلسلة()})
اطبع(مخطط.صالح({"اسم": "أ"}, قاعدة), مخطط.صالح({"اسم": 5}, قاعدة))   // صح غلط

نتيجة (النتيجة والخيار)

بدل رمي الأخطاء: نتيجة تمثل نجاحاً أو فشلاً، وخيار يمثل وجود قيمة أو غيابها.

الدالة الوظيفة
نجاح(قيمة) · فشل(خطأ) ينشئ نتيجة ناجحة / فاشلة
محاولة(ف, ...وسائط) ينفّذ ف ويلتقط الخطأ في نتيجة
اعد_المحاولة(ف, مرات=3, تأخير=0, مضاعف=1) يعيد المحاولة عند الفشل
تجميع(قائمة) · تجميع_اخطاء(قائمة) · فرز(قائمة) دمج قائمة نتائج
شيء(قيمة) · غائب() · من_قيمة(قيمة) · من_قاموس(م, مفتاح) · من_قائمة(ق, فهرس) ينشئ خيار

أعضاء نتيجة: .هل_ناجح() .هل_فاشل() .افتح() .افتح_او(افتراضي) .افتح_او_احسب(ف) .افتح_خطأ() .حول(ف) .حول_خطأ(ف) .ثم(ف) .او_ثم(ف) .او(بديل) .رشح(شرط, خطأ) .اذا_نجح(ف) .اذا_فشل(ف) .طابق(م) .الى_خيار() .الى_نص(). أعضاء خيار: .هل_موجود() .هل_غائب() .افتح() .افتح_او(افتراضي) .حول(ف) .ثم(ف) .او(بديل) .رشح(شرط) .اذا_وجد(ف) .طابق(م) .الى_نتيجة(خطأ) .الى_نص().

استورد "نتيجة"
اطبع(نتيجة.نجاح(5).حول(س => س * 2).افتح())      // 10
اطبع(نتيجة.فشل("سيء").افتح_او(0))                // 0
اطبع(نتيجة.شيء(3).افتح_او(0), نتيجة.غائب().افتح_او(9))   // 3 9

ألوان

كل دالة تأخذ نصاً وتعيده ملفوفاً بأكواد ANSI (وتتعطل تلقائياً إن لم تكن المخرجات طرفية أو ضُبط NO_COLOR):

الدالة الوظيفة
اسود احمر اخضر اصفر ازرق بنفسجي سماوي ابيض رمادي (ن) ألوان النص (وللفاتح: احمر_فاتح وأخواتها)
خلفية_اسود خلفية_احمر … (ن) ألوان الخلفية
غامق خافت مائل مسطر وميض معكوس مشطوب (ن) التنسيق
لون(اسم, ن) · لون256(رقم, ن) · خلفية256(رقم, ن) · rgb(ر,غ,ب,ن) · خلفية_rgb · هيكس("ff8800", ن) · خلفية_هيكس ألوان مخصصة
ضبط(قيمة) يفعّل/يعطّل الألوان يدوياً
وسوم(نص) وسوم ملونة: ألوان.وسوم("[احمر]خطأ[/] عادي")
ازل(ن) · طول_مرئي(ن) يحذف أكواد الألوان / الطول الظاهر
اطار(نص, عنوان="", حشو=1) يرسم إطاراً حول النص
شريط_تقدم(نسبة, عرض=20, ممتلئ, باقي) شريط_تقدم(0.5, 10) ← █████░░░░░ 50%

اختبار (إطار اختبارات لبرامجك ومكتباتك)

استورد "اختبار"
اختبار.مجموعة("حساب", دالة() {
  اختبار.اختبر("جمع", دالة() { اختبار.يساوي(1 + 1, 2) })
  اختبار.اختبر("قسمة على صفر", دالة() { اختبار.يرمي(دالة() { خل ز = 1 / 0 }) })
})
اختبار.شغل_الكل()        // يطبع التقرير؛ وإن فشل اختبار ينهي البرنامج برمز 1
الدالة الوظيفة
مجموعة(اسم, ف) · اختبر(اسم, ف) تنظيم الاختبارات
ارجئ(اسم, ف) · فقط(اسم, ف) تخطّي اختبار / تشغيل هذا فقط
قبل_كل(ف) بعد_كل(ف) قبل_الكل(ف) بعد_الكل(ف) خطافات
يساوي(فعلي, متوقع) لا_يساوي(أ, ب) قريب(أ, ب, دقة) اكبر_من اصغر_من تأكيدات المقارنة
هو_صح(ق) هو_غلط(ق) هو_عدم(ق) ليس_عدم(ق) تأكد_ان(شرط, رسالة) تأكيدات القيم
من_نوع(ق, ن) طول_يساوي(ق, ن) يحتوي(حاوية, عنصر) لا_يحتوي يطابق(س, ن) تأكيدات الأنواع والمحتوى
يرمي(ف, ن) · لا_يرمي(ف) تأكيدات الأخطاء
وهمية(ناتج) · استدعيت_مرات(م, عدد) · استدعيت_بوسائط(م, ...وسائط) دوال وهمية (mocks)
شغل_الكل(انهاء=صح, مرشح, تقرير=غلط) يشغّل الاختبارات ويطبع التقرير. مع انهاء=صح (الافتراضي) ينهي البرنامج برمز 1 عند أي فشل؛ وإن كان انهاء=غلط يعيد قاموس النتائج

سجل

الدالة الوظيفة
جديد(اسم, حقول) مسجِّل باسم، بطرق .تصحيح .معلومة .تحذير .خطأ .حرج و.مع(حقول) و.فرعي(اسم)
تصحيح(...) معلومة(...) تحذير(...) خطأ(...) حرج(...) تسجيل عام مباشر
مستوى(م) أدنى مستوى يُطبع
ملف(مسار) · صيغة(ص) · اضف_معالج(ف) · امسح_المعالجات() المخرج والصيغة ومعالجات مخصصة

ذاكرة (ذاكرة مؤقتة)

ذاكرة.جديد(سعة=0, عمر=0) تعيد ذاكرة بحد أقصى سعة عنصر (الأقدم استعمالاً يُطرد) وعمر افتراضي عمر ثانية (0 = بلا حد). أعضاؤها: .ضع(مفتاح, قيمة, عمر) .خذ(مفتاح, افتراضي) .يوجد .احذف .امسح .نظف .حجم .مفاتيح .احسب(مفتاح, ف, عمر) (يحسب القيمة بالدالة مرة واحدة ثم يخزنها) .احصائيات(). وذاكرة.احفظ_نتيجة(ف, عمر, سعة) تعيد دالة تخزّن نتائج ف تلقائياً.

بث (مرسل أحداث)

استورد "بث"
خل ب = بث.جديد()
ب.على("رسالة", دالة(نص) { اطبع("وصلت:", نص) })
ب.ارسل("رسالة", "أهلا")     // وصلت: أهلا

الأعضاء: .على(حدث, ف) .مرة(حدث, ف) (مرة واحدة) .الغ(حدث, ف) .امسح(حدث) .ارسل(حدث, ...وسائط) .عدد_المستمعين(حدث) .اسماء_الاحداث().

عمال (التوازي)

العنصر الوظيفة
مجمع_جديد(عدد, معالج) مجمع من عدد عملية عاملة: .حول(قائمة) (وعد بنتائج المعالج على كل عنصر بالتوازي) و.نفذ(بيانات) و.اغلق()
انشئ(ف) عملية عاملة واحدة: .ارسل(رسالة) .استقبل() .عند_رسالة(ف) .اطلب(رسالة) (وعد بالرد)
خادم_طلبات(معالج) يبني خادم طلبات بعمال
قناة قناة اتصال بين العمليات: .ارسل .استقبل
استورد "عمال"
غير_متزامن دالة رئيسي() {
  خل م = عمال.مجمع_جديد(2, دالة(ن) { ارجع ن * ن })
  اطبع(انتظر م.حول([1, 2, 3]))    // [1، 4، 9]
  م.اغلق()
}
شغل(رئيسي)

وسائط (قراءة سطر الأوامر)

استورد "وسائط"
خل نتيجة = وسائط.حلل(["--اسم", "علي", "-v", "ملف"], {"اسم": {"نوع": "نص"}, "v": {"نوع": "منطقي"}})
// {"خيارات": {"اسم": "علي"، "v": صح}، "موضعية": ["ملف"]، "اخطاء": []، "مجهولة": ["-v"]}
الدالة الوظيفة
حلل(قائمة, مواصفات) يحلل القائمة (عادةً وسائط) إلى {خيارات، موضعية، اخطاء، مجهولة}. المواصفات قاموس: اسم الخيار ← {نوع، افتراضي، اختصار}
مساعدة(مواصفات, عنوان) نص مساعدة منسّق
حلل_او_اخرج(قائمة, مواصفات, وصف, امر_اسم) يحلل ويطبع المساعدة/الأخطاء ويخرج عند الحاجة
حلل_اوامر(قائمة, اوامر, خيارات) · مساعدة_اوامر(...) برامج متعددة الأوامر (مثل git add)

7) المرادفات

لكل كلمة مفتاحية ودالة وطريقة ومكتبة مرادفات تعمل مثل الأصل تماماً، فتكتب بالأسلوب الذي تفضّله. لا فرق في الهمزات (إذا = اذا) ولا بين ة وه ولا في التشكيل. الكلمة المعلَّمة ⭐ هي القياسية (التي يعيدها solan fmt --قياسي). الجداول التالية مأخوذة من جدول المحرك نفسه.

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

المعنى الكلمات
تعريف متغير خل ⭐، متغير، ليكن، اجعل، عرف، فليكن
تعريف ثابت ثابت ⭐، دائم، قيمة_ثابتة
تعريف دالة دالة ⭐، دالّة، وظيفة، اجراء، إجراء، وظيفه
شرط اذا ⭐، إذا، لو، في_حال، اذا_كان، إذا_كان، ان_كان، في_حالة
وإلا والا ⭐، وإلا، والّا، غير_ذلك، خلاف_ذلك، بخلاف_ذلك، سوى_ذلك، و_الا
وإلا-إذا والا_اذا ⭐، وإلا_إذا، والا_لو، او_اذا، او_لو، غير_ذلك_اذا
حلقة طالما طالما ⭐، مادام، ما_دام، بينما، طول_ما
حلقة لكل لكل ⭐، لاجل، لأجل، من_اجل، من_أجل
تكرار عدد مرات كرر ⭐، كرّر، كرر_مرات
في / ضمن في ⭐، ضمن
إيقاف الحلقة توقف ⭐، اكسر، قف، انهي_الحلقة
متابعة الحلقة استمر ⭐، تابع، واصل، تخطى، تجاوز
إرجاع ارجع ⭐، اعد، أعد، رجع، رجّع، ارجاع، اعطي، أعطِ
صح صح ⭐، صحيح، حقيقي، نعم، صدق
غلط غلط ⭐، خاطئ، كذب، زائف
عدم عدم ⭐، فارغ، لاشيء، لا_شيء، خالي، بلا_قيمة
و و ⭐، وكذلك
أو او ⭐، أو
ليس ليس ⭐، ليست، نفي
تعريف صنف صنف ⭐، فئة، كلاس، قالب
الكائن الحالي هذا ⭐، هذه، نفسه، ذاتي
الصنف الأب الاب ⭐، الأب، الاصل، الأصل
وراثة يرث ⭐، يمتد، يمتد_من، يشتق_من، ترث، يرث_من
محاولة حاول ⭐، جرب، جرّب
التقاط الخطأ امسك ⭐، التقط، عند_الخطا، عند_الخطأ
أخيرا اخيرا ⭐، أخيراً، اخيراً، في_النهاية، نهاية
رمي خطأ ارمي ⭐، اطلق، ارفع، القي، ألقِ، ارم
استيراد استورد ⭐، استدعي، اجلب_مكتبة، ادرج_مكتبة
باسم باسم ⭐، كاسم، بمسمى
تبديل تبديل ⭐، طابق، حسب
دالة غير متزامنة غير_متزامن ⭐، غير_متزامنة
مولّد مولد ⭐، مولّد
انتظار انتظر ⭐، ترقب
إنتاج قيمة انتج ⭐، أنتج، ولد، ولّد

كلمات سياقية (لا تُحجز كأسماء متغيرات)

المعنى الكلمات
حالة داخل تبديل حالة ⭐، عندما، حين، لو_كان
افتراضي داخل تبديل افتراضي ⭐، غير_ذلك_افتراضي، سوى
عضو ساكن ساكن ⭐، ساكنة، استاتيكي
خاصية (getter) خاصية ⭐، صفة، احصل
تعداد تعداد ⭐، قائمة_ثابتة، تعداد_ثابت
استيراد من من ⭐، من_مكتبة

الدوال العامة

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

طرق النصوص والقوائم والقواميس

الأصل المرادفات
طول حجم، عدد
قسم قطع، فصل، جزّئ
نظف قص، شذب، احذف_الفراغات
كبير حروف_كبيرة، كبّر
صغير حروف_صغيرة، صغّر
يبدأ_ب يبتدئ_ب، يبدا_بـ
يحتوي يشمل، فيه، يتضمن، تضمن
ابدل استبدل، بدّل، غيّر
جزء شريحة، اقتطع
ابحث موضع، فهرس، اين
كرر كرّر، ضاعف
اعكس اقلب، عكس
حروف احرف
اضف ألحق، الحق، ادفع، أضف، اضافة، زد
ادرج اقحم، ادخل_في
احذف ازل، امحي، امح، انزع
اسحب انزع_الاخير، ابرز
ادمج اربط، ضم، صل
رتب افرز، فرز، صنّف
حول طبق، خرّط، حوّل، خريطة
رشح صفي، فلتر، اختر_حسب
اطوي قلص، جمّع، اختزل
نفذ لكل_عنصر، كرر_على، مرّ_على
انسخ استنسخ، نسخة
امسح افرغ، فرّغ
مجموع اجمع، جمع_العناصر
مفاتيح المفاتيح، اسماء
قيم القيم، محتويات
ازواج عناصر، ازواج_القيم
دمج ادمج_مع، حدّث، حدث
جد اوجد، ابحث_عن، جد_اول
اي بعض، اي_منها، يوجد
كل جميع، الكل، كلها
سطور اسطر، الاسطر
نسق صيغ

أسماء المكتبات المدمجة

الأصل المرادفات
رياضيات حساب، رياضة، ارقام
عشوائي عشوائية، حظ، صدفة
زمن وقت، توقيت
نظام نظام_التشغيل، نظام_الكمبيوتر
ملفات ملف، ملفات_النظام
جيسون json، ترميز_جيسون
شبكة ويب، انترنت، انترنيت، اتصالات
سوكت مقبس، مآخذ
ويبسوكت مقبس_ويب، ويب_سوكت
تشفير تعمية، كريبتو
نمط تعبير_نمطي، ريجكس، تعابير
ضغط زيب، ارشفة
حلقة احداث، حلقة_الاحداث
ضخم اعداد_كبيرة، عدد_ضخم
مسارات مسار، مسارات_الملفات
ألوان الوان، تلوين
سجل تسجيل، لوغ، سجلات
اختبار اختبارات، فحص
وسائط معاملات_الاوامر، سطر_الاوامر
جداول csv، جدول

دوال المكتبات

المكتبة الأصل المرادفات
رياضيات جذر جذر_تربيعي
رياضيات ارضي سفلي، ارضية، قاع
رياضيات سقف علوي، سقفي
رياضيات مطلق قيمة_مطلقة، معياري
رياضيات قرب دور، تقريب
رياضيات قوة اس_قوة، اسّ
رياضيات اكبر اعلى، اقصى، اكبر_قيمة
رياضيات اصغر ادنى، اقل، اصغر_قيمة
رياضيات باي ط
رياضيات لوغ لوغاريتم
رياضيات جيب جا
رياضيات جتا جتا_زاوية
رياضيات ظل ظا
عشوائي رقم عشوائي_عشري
عشوائي صحيح عدد_صحيح، عدد_عشوائي
عشوائي اختر التقط_عشوائيا، اخذ
عشوائي اخلط بعثر، خلط
عشوائي بذرة بذر
زمن الان حاليا، الوقت_الان
زمن نوم تمهل، انتظر_مدة
زمن تاريخ تقويم
زمن تنسيق صيغة، نسق_وقت
زمن ساعة عداد، مؤقت_دقيق
زمن من_تاريخ الى_طابع_زمني
نظام بيئة متغير_بيئة، متغير
نظام اخرج انهي، انتهاء، اغلق_البرنامج
نظام نفذ شغل_امر، امر
نظام شغل تشغيل، شغل_امر_بلا_ناتج
نظام عملية ابدأ_عملية، شغل_عملية
نظام مسار المجلد_الحالي
ملفات اقرا اقرأ، قراءة، حمل
ملفات اكتب احفظ، كتابة، خزن
ملفات الحق ضيف، الحاق
ملفات موجود هل_موجود، يوجد
ملفات احذف امسح_ملف، ازل
ملفات قائمة محتويات، اعرض_المجلد
ملفات انشئ_مجلد مجلد_جديد، اصنع_مجلد
جيسون ترميز الى_جيسون، اكتب
جيسون فك من_جيسون، حلل، اقرا
شبكة جلب اطلب، احضر، طلب، جلب_رابط
شبكة خادم شغل_خادم، خدمة
شبكة ترميز_رابط ترميز_url
سوكت اتصل وصل
سوكت استمع اصغ
سوكت اقبل استقبل_اتصال
سوكت ارسل ابعث
سوكت استقبل تسلم
سوكت اغلق اقفل، انه
سوكت سطر اقرا_سطر
ويبسوكت اتصل وصل
ويبسوكت ارسل ابعث
ويبسوكت استقبل تسلم
ويبسوكت اغلق اقفل
نمط ابحث جد، اعثر
نمط هل يطابق، مطابقة
نمط كل جميع
نمط ابدل استبدل
نمط قسم فصل
حلقة بعد بعد_مدة، مؤقت
حلقة كل كل_مدة، دوري
حلقة شغل ابدأ، شغل_الاحداث
حلقة اوقف قف، انهي
ضغط فك فك_الضغط

8) الصلاحيات والأمان

افتراضياً للبرنامج كل الصلاحيات. يمكنك تقييدها على طريقة Deno، بست فئات: قراءة كتابة شبكة تنفيذ بيئة اصلي (والمقصود بـ اصلي تحميل المكتبات الأصلية وffi)، ويجمعها الكل.

solan --اسمح-قراءة=/بيانات --اسمح-كتابة=/مخرجات --اسمح-شبكة=api.example.com سكربت.سو
solan --امنع=تنفيذ,شبكة سكربت.سو      # كل شيء مسموح عدا التنفيذ والشبكة
solan --اسمح=قراءة سكربت.سو            # كل ما عدا القراءة ممنوع
solan --آمن سكربت.سو                   # قراءة وبيئة فقط
  • --اسمح=فئة,فئة يمنح الفئات المذكورة ويمنع كل ما عداها.
  • --اسمح-قراءة=/مسار1,/مسار2 و--اسمح-كتابة=... يحصران الوصول في مجلدات محددة (تُفحص بعد حل الروابط الرمزية و..).
  • --اسمح-شبكة=مضيف1,مضيف2 يحصر الشبكة في مضيفين (يطابق المضيف تماماً أو نطاقاً فرعياً منه).
  • --امنع=فئة,... يسحب الفئات المذكورة.
  • المكافئات الإنجليزية: --allow و--allow-read= و--allow-write= و--allow-net= و--deny و--safe، وأسماء الفئات: read write net exec env native all.
  • فئة غير معروفة تعطي صلاحية غير معروفة: ... ورمز خروج 64.

عند المخالفة يُرمى خطأ يمكن مسكه:

خطأ: الصلاحية غير ممنوحة لهذا المسار: كتابة (/tmp/x.txt)
خطأ: الصلاحية غير ممنوحة: تنفيذ (شغّل بـ --اسمح=تنفيذ)
خطأ: الصلاحية غير ممنوحة: شبكة (المضيف 127.0.0.1)

متغير البيئة SOLAN_SAFE=1 يفعّل الوضع الآمن بلا خيارات. وبهذه الصلاحيات يمكنك تشغيل شيفرة غير موثوقة بحذر، لكنها ليست صندوق رمل كاملاً؛ للتبليغ عن الثغرات انظر SECURITY.md.


9) المكتبات والحزم: استعمالها وتنزيلها

المكتبات في سولان مستودعات git عادية: لا خادم مركزي ولا خطوة بناء. المكتبة تُخزَّن مرة واحدة في مجلد المستخدم (~/.solan/store) وتُشارَك بين كل المشاريع. المشروع يضم ملفين فقط: solan.json (ما تريده) وsolan.lock (ما حصلتَ عليه بالضبط). لا يوجد مجلد مكتبات داخل المشروع. يلزم git عند التثبيت فقط.

البدء: مشروع يستعمل مكتبة

mkdir مشروعي && cd مشروعي
solan init                                   # ينشئ solan.json
solan add owner/مساعد_نصوص                   # من GitHub: يختار أعلى إصدار ويثبّته
solan add https://gitlab.com/a/b.git          # من أي مستودع git (https و ssh و file)
solan add اسمي=owner/repo@^1.2.0              # باسم استيراد مخصص ونطاق إصدار
solan add ./libs/محلي                         # مكتبة محلية أثناء التطوير

ثم في الكود:

استورد "مساعد_نصوص"
اطبع(مساعد_نصوص.مرحبا("عالم"))

وإن تغيّر المشروع على جهاز آخر: solan install يثبّت ما في solan.json ويلتزم بالقفل.

solan.json (المشروع)

{
  "الاسم": "بوتي",
  "النسخة": "0.1.0",
  "الاعتماديات": {
    "ادوات": "mylang/tools@^1.2.0",
    "مساعد": "git+https://gitlab.com/a/b.git@~2.1.0",
    "تجريبي": "owner/repo#main",
    "محلي": "./libs/محلي"
  }
}
  • مفتاح الاعتمادية هو اسم الاستيراد ويجوز أن يكون عربياً: استورد "ادوات".
  • المصدر: owner/repo[@نطاق] (GitHub)، أو رابط git كامل (https:// وssh:// وgit@host:path وfile://)، أو #فرع أو #التزام، أو مسار محلي (للتطوير؛ يُربط ولا يُنسخ؛ للمشروع الرئيسي فقط).
  • نطاقات الإصدار: 1.2.3 و^1.2.3 و~1.2.3 و>=1.0.0 <2.0.0 و1.x و* وlatest. لا يجوز الجمع بين نطاق و#.
  • الإصدارات هي وسوم git بالشكل vX.Y.Z؛ وسوم ما قبل الإصدار تُتجاهل.
  • يُقبل أيضاً الأسماء الإنجليزية للمفاتيح: name وversion وdependencies وentry (لكن لا يجوز المفتاحان العربي والإنجليزي معاً للاعتماديات).

أوامر الحزم

الأمر الوظيفة
solan init [--lib] ينشئ solan.json (ومع --lib هيكلة مكتبة كاملة)
solan add [اسم=]مصدر[@نطاق] يضيف ويثبّت (بلا نطاق يكتب ^ لآخر وسم). --as اسم بديل لـ اسم=. عند فشل التثبيت يُعاد solan.json كما كان
solan install يثبّت ما في solan.json ويحترم القفل. --local يفضّل المتجر المحلي دون شبكة، و--quiet
solan install --frozen القفل فقط بلا ترقية، يتحقق من البصمات ويعيد جلب أي حزمة معدَّلة (للـCI)
solan remove اسم... يحذف اعتماديات (المتجر المشترك يبقى)
solan update [اسم] [--major] يرقّي ضمن النطاق، و--major يغيّر النطاق للإصدار الرئيسي الأحدث
solan list [--tree] [--store] الاعتماديات (والمتداخلة مع --tree)، أو محتوى المتجر كله
solan outdated الحالي والمسموح والأحدث لكل اعتمادية
solan why اسم من يطلب هذه الحزمة ولماذا هي مثبتة
solan verify يقارن بصمات المتجر بالقفل
solan prune [--dry-run] يحذف من المتجر ما لا يستعمله أي مشروع مسجَّل
solan cache clean يمسح التنزيلات المؤقتة
solan publish [--dry-run] [--push] يفحص المكتبة وينشئ الوسم vX.Y.Z (ويدفعه مع --push) (انظر القسم 10)

الأسماء العربية مقبولة أيضاً: ثبت اضف ازل قائمة حدث تحقق قديمة لماذا تنظيف كاش انشر بدء. تُشغَّل الأوامر من أي مجلد فرعي داخل المشروع (يُكتشف solan.json صعوداً). خارج أي مشروع تعمل install مصدر وremove وlist على المكتبات العامة القديمة (~/.solan/modules)، و--global يفرض ذلك داخل مشروع.

ما يحدث عند التثبيت وعند التشغيل

  1. solan add يقرأ وسوم المستودع (git ls-remote --tags) ويختار أعلى إصدار يحقق النطاق.
  2. يجلب git clone --depth 1 إلى مجلد مؤقت، يتحقق من الروابط الرمزية والحجم، يحسب بصمة sha256 لشجرة الملفات، ثم ينقله ذرياً إلى ~/.solan/store/<المضيف>/<owner>/<repo>/<الإصدار>/.
  3. يكتب solan.lock فيه الالتزام (commit) والبصمة لكل حزمة (المباشرة والمتداخلة).
  4. عند تشغيل برنامجك يقرأ المحرك القفل ويصل مباشرة لمسار الحزمة في المتجر (بلا شبكة ولا كتابة في المشروع).
  5. إن غاب القفل أو تغيّر solan.json أو فُقدت حزمة: تثبيت تلقائي لمرة واحدة (يفضّل المتجر المحلي) ثم يكمل التشغيل. لا يعمل التثبيت التلقائي مع --امنع=شبكة أو --امنع=تنفيذ.

ترتيب حلّ الاسم في استورد "x": مسار نسبي ← مكتبة مدمجة/قياسية (لا تُغطّى أبداً) ← اعتماديات الحزمة/المشروع من القفل ← المسارات القديمة. كل حزمة تحلّ اعتمادياتها من قفلها الخاص، فلا تتعارض إصدارات مختلفة لحزمتين. ويمكن استيراد ملف فرعي من حزمة: استورد "ادوات/src/عميل".

أين تُخزَّن المكتبات (مجلد البيت)

يُختار أول مسار قابل للكتابة بالترتيب: (1) SOLAN_HOME (صريح؛ إن لم يكن قابلاً للكتابة يظهر خطأ)، (2) على ويندوز %LOCALAPPDATA%\Solan، (3) ~/.solan، (4) <المشروع>/.solan عندما يكون البيت للقراءة فقط (حاويات)، (5) <temp>/solan-<معرّف المستخدم>.

<البيت>/store/<المضيف>/<owner>/<repo>/<الإصدار>/   الحزم المنزَّلة (دائمة، مشتركة)
<البيت>/cache/                                    تنزيلات مؤقتة (solan cache clean)
<البيت>/projects.json                             قائمة المشاريع لأمر prune

الاختلافات بين الأنظمة

الموضوع السلوك
فاصل المسارات داخلياً / دائماً (تُحوَّل مسارات ويندوز)
حالة الأحرف معرّفات GitHub/GitLab/Bitbucket/Codeberg تُحوَّل لأحرف صغيرة (Owner/Repo = owner/repo)
نهايات الأسطر تُجلب دائماً بـ LF (core.autocrlf=false) فتتطابق البصمة على كل الأنظمة
الشبكة بلا مطالبات (GIT_TERMINAL_PROMPT=0)، وقطع الاتصال البطيء بعد 30 ثانية، ومهلة اتصال ssh 20 ثانية
ويندوز: المسارات الطويلة الحد الافتراضي 260 حرفاً: فعّل «Long Paths» أو اجعل SOLAN_HOME قصيراً (مثل C:\so)

الأمان والقيود

القيد القيمة
سكربتات التثبيت لا يُنفَّذ أي كود من المكتبة وقت التثبيت أو النشر
الروابط الرمزية ممنوعة داخل المكتبة (تُرفض عند التثبيت والنشر)
عدد الملفات / الحجم 5000 ملف / 50 ميغابايت كحد أقصى
عمق الاعتماديات / عددها 16 مستوى / 500 حزمة
البروتوكولات https وhttp وssh وgit وfile فقط (ext:: مرفوض)
سلامة الاسترجاع الالتزام والبصمة في القفل؛ solan install --frozen وsolan verify يكشفان أي تلاعب
التوقيع الرقمي لا يوجد؛ الأمان بالالتزام والبصمة المسجَّلين في القفل

حدود معروفة: التنزيل متسلسل (حزمة بعد حزمة)، وsolan prune لا يعرف إلا المشاريع التي ثبّتَّ فيها بهذا الإصدار أو أحدث، والحزم الثنائية الأصلية لا تُختار حسب المنصة.


10) كتابة مكتبة ونشرها

المكتبة مستودع git فيه ملف solan.json وكود .سو. النشر = وسم git.

10.1) البدء السريع

mkdir مساعد_نصوص && cd مساعد_نصوص
git init
solan init --lib          # ينشئ الهيكلة (الاسم = اسم المجلد)
solan tests/اختبار.سو     # يشغّل اختبار المكتبة
git add -A && git commit -m "أول نسخة"
solan publish --dry-run   # يفحص كل شيء دون نشر
solan publish --push      # ينشئ الوسم v0.1.0 ويدفعه إلى origin

ثم أي شخص يكتب في مشروعه solan add owner/مساعد_نصوص ثم استورد "مساعد_نصوص".

10.2) هيكل المجلد

مساعد_نصوص/
├── solan.json          بيان المكتبة (إجباري)
├── رئيسي.سو            نقطة الدخول (الاسم الافتراضي)
├── src/                ملفاتك الداخلية (اختياري)
├── tests/اختبار.سو     اختباراتك (اختياري)
├── README.md
└── LICENSE

الإجباري فقط solan.json وملف الدخول. لا مجلد بناء ولا ملف قفل داخل المكتبة (القفل للمشاريع لا للمكتبات). القالب الذي ينشئه solan init --lib يحتوي دالة مرحبا(اسم) واختباراً يشغَّل بـ solan tests/اختبار.سو.

10.3) solan.json للمكتبة

{
  "الاسم": "مساعد_نصوص",
  "النسخة": "1.0.0",
  "الوصف": "دوال مساعدة صغيرة للنصوص",
  "المؤلف": "اسمك",
  "الرخصة": "MIT",
  "المدخل": "رئيسي.سو",
  "الاعتماديات": {
    "ادوات": "owner/tools@^1.2.0"
  }
}
الحقل (والبديل الإنجليزي) الوظيفة يستعمله النظام؟
الاسم / name اسم المكتبة. إجباري عند solan publish publish فقط
النسخة / version رقم الإصدار MAJOR.MINOR.PATCH نعم: publish يتحقق منه وينشئ الوسم، والتثبيت يحذّر إن خالف الوسم
الوصف · المؤلف · الرخصة معلومات للقرّاء لا
المدخل / entry ملف الدخول (مسار نسبي داخل المكتبة، دون ..). الافتراضي رئيسي.سو نعم
الاعتماديات / dependencies ما تحتاجه مكتبتك نعم

10.4) الإصدار: أين يوضع وكيف يتغير

الإصدار له مكانان يجب أن يتطابقا:

  1. النسخة داخل solan.json (مثلاً 1.2.0) — هذا ما تعرفه اللغة عن مكتبتك.
  2. وسم git بالشكل v + النسخة (مثلاً v1.2.0) — هذا ما يقرؤه نظام الحزم لاختيار الإصدار (git ls-remote --tags)، فهو الذي ينشر الإصدار فعلاً.

solan publish يتولى الاثنين: يتحقق أن النسخة صالحة ثم ينشئ الوسم المطابق. خطوات نشر نسخة جديدة:

# 1) عدّل الكود ثم ارفع "النسخة" في solan.json
git commit -am "إصلاح كذا"        # 2) احفظ
solan publish --push               # 3) انشر (ينشئ الوسم v1.3.0 ويدفعه)

معنى الأرقام (SemVer):

ارفع متى أثره على المستهلكين
PATCH (1.0.0 ← 1.0.1) إصلاح خطأ دون تغيير الواجهة يحصلون عليه بـ solan update
MINOR (1.0.0 ← 1.1.0) إضافة ميزة متوافقة يحصلون عليه بـ solan update (نطاق ^1.0.0)
MAJOR (1.0.0 ← 2.0.0) تغيير يكسر الواجهة لا يحصلون عليه إلا بـ solan update --major

انتبه لنطاق ^ مع الإصدارات الصفرية: ^0.4.1 يعني >=0.4.1 <0.5.0، و^0.0.3 يعني 0.0.3 فقط. لذلك 0.x تعني «غير مستقرة»؛ انشر 1.0.0 عندما تثبت واجهتك. وسوم ما قبل الإصدار (v1.0.0-beta) وأي وسم ليس vX.Y.Z تُتجاهل.

publish يرفض النشر عند أي من:

  • الاسم أو النسخة مفقودة، أو النسخة ليست بالشكل 1.2.3 (يرفض 1.2 وv1.2.3 و1.2.3-beta).
  • ملف المدخل غير موجود أو يحوي ...
  • اعتمادية بمسار محلي (./...) أو باسم مكتبة قياسية.
  • المجلد ليس مستودع git، أو توجد تغييرات غير ملتزَم بها (توجد تغييرات غير مُلتزَم بها؛ نفّذ commit أولا).
  • الوسم موجود مسبقاً، أو يوجد وسم أحدث من النسخة.
  • رابط رمزي، أو أكثر من 5000 ملف، أو حجم فوق 50 ميغابايت.
  • اسم ملف لا يصلح على ويندوز/ماك: أحرف ممنوعة (< > : " | ? * \)، أو ينتهي بمسافة أو نقطة، أو اسم محجوز (CON NUL COM1...)، أو ملفان يختلفان بحالة الأحرف فقط.

10.5) كتابة الكود

ما الذي يُصدَّر؟ كل ما تعرّفه في المستوى الأعلى من ملف الدخول (دوال ومتغيرات وثوابت وأصناف، وحتى الوحدات التي استوردتها) يصبح عضواً في الوحدة. لا توجد كلمة export. للتحكم بالواجهة العامة: ضعها في رئيسي.سو كدوال صغيرة تستدعي ملفاتك الداخلية، وابدأ أسماء الأشياء الداخلية بشرطة سفلية _ (اصطلاح؛ اللغة لا تمنع الوصول إليها).

// رئيسي.سو
استورد "./src/حروف"

دالة اعكس(نص) { ارجع حروف.اعكس_نص(نص) }     // واجهة عامة
دالة _مساعدة_داخلية() { ارجع 1 }              // داخلية بالاصطلاح

الاستيراد داخل المكتبة:

الشكل المعنى
استورد "./حروف" أو "../x" ملف نسبي إلى الملف الذي يحوي الاستيراد (وليس إلى مجلد البرنامج الرئيسي)
استورد "ادوات" اعتمادية معلنة في solan.json الخاص بمكتبتك
استورد "ادوات/src/عميل" ملف فرعي داخل الاعتمادية
استورد "نظام" مكتبة مدمجة أو قياسية

الاسم الذي تُربط به الوحدة هو اسم الملف (أو المجلد) دون الامتداد، أو الاسم الذي سمّاه المستهلك في الاعتماديات. الوحدة تُحمَّل مرة واحدة وتُخزَّن، والاستيراد الدائري آمن (لا حلقة لا نهائية، لكن الوحدة قد تكون ناقصة التعريف لحظة استيرادها الدائري). تذكّر أن الأسماء تُطبَّع (قيمة = قيمه)، فلا تعرّف اسمين يختلفان بالهمزات أو التاء فقط.

10.6) اختبار المكتبة

اكتب اختبارات في tests/ تستورد مكتبتك نسبياً وشغّلها solan tests/اختبار.سو. استعمل مكتبة اختبار (القسم 6)؛ فهي تنهي البرنامج برمز غير صفري عند الفشل، فتصلح للـCI. مجلد tests/ ينتقل مع المكتبة عند التثبيت لكن لا يستعمله المستهلك.

10.7) اعتماديات مكتبتك

تعلنها في solan.json بالصيغة نفسها للمشاريع. كل مكتبة تحلّ اعتمادياتها بنفسها: لو احتاجت مكتبتان نسختين مختلفتين من ادوات تتعايشان بلا تعارض. مفتاح الاعتمادية هو اسم الاستيراد داخل مكتبتك فقط. لا يجوز مسار محلي (./x) في مكتبة منشورة.

الأسماء المحجوزة (مكتبات مدمجة وقياسية) لا تصلح اسماً لاعتمادية ولا لمكتبتك عند الاستهلاك: ffi ألوان اختبار بث تشفير تواريخ جداول جيسون حزم حلقة خادم_اللغة ذاكرة رياضيات زمن سجل سوكت شبكة ضخم ضغط عرض عشوائي عمال قاعدة_سريعة قوالب مجموعات مخطط مسارات ملفات نتيجة نصوص نظام نمط وسائط ويبسوكت.

10.8) مكتبات أصلية (C) داخل الحزم

يمكن لملف الدخول أن يكون وحدة أصلية (.so أو .dylib أو .dll) لأن الاستيراد يتعرف عليها بالامتداد. لكن نظام الحزم لا يبني ولا يختار ملفاً حسب المنصة، فتوزيع ملف ثنائي واحد يعمل على منصة واحدة فقط. للتوزيع الواسع اكتب المكتبة بسولان أو وزّع شيفرة C مع تعليمات بناء.

10.9) أخطاء شائعة

الرسالة السبب الحل
الاسم 'x' محجوز للمكتبة القياسية سمّيت اعتمادية باسم مكتبة مدمجة solan add اسم_آخر=owner/x
لا يوجد إصدار يطابق '^2.0.0' لا وسم v2.x.x في المستودع انشر وسماً أو غيّر النطاق
لا يوجد solan.lock صالح --frozen بلا قفل شغّل solan install أولاً وارفع القفل
الوسم v1.0.0 موجود مسبقاً نشرت هذه النسخة ارفع النسخة في solan.json
يوجد وسم أحدث من النسخة نسخة أقل من وسم موجود ارفع النسخة فوق آخر وسم
تنبيه: وسم X لا يطابق النسخة المعلنة وسم v1.2.0 لكن النسخة في الملف شيء آخر صحّح الملف وانشر نسخة جديدة (لا تعدّل وسماً منشوراً)
الحزمة تحتوي رابطاً رمزياً رابط رمزي في المستودع احذفه
ملفان يختلفان بحالة الأحرف فقط Readme.md وREADME.md أبقِ واحداً
git غير مثبت git غير موجود في PATH ثبّت git

10.10) قائمة تحقق قبل النشر

  1. solan tests/اختبار.سو ينجح.
  2. solan publish --dry-run ينجح.
  3. النسخة ارتفعت، والتغييرات محفوظة بـ commit.
  4. اختبرتها من مشروع فارغ: solan add owner/مكتبتي ثم استورد ثم استدعاء.
  5. وثّقت الواجهة العامة في README.md المكتبة.

11) مكتبات أصلية بلغة C وFFI

11.1) استدعاء مكتبات C مباشرة (ffi)

استورد "ffi"
خل جذر = ffi.ربط(عدم, "sqrt", "d(d)")     // (مكتبة أو عدم، اسم الدالة، التوقيع)
اطبع(جذر(2))                               // 1.4142135623730951
خل ل = ffi.افتح("libm.so.6")
اطبع(ffi.ربط(ل, "cbrt", "d(d)")(27))       // 3

التوقيع نوع_الإرجاع(الوسائط)، والأنواع: i (int32) · l (int64) · p (مؤشر) · d (double) · s (نص) · b (منطقي) · v (void). أمثلة: "d(d)" و"i(ss)" و"s(s)" و"v()". وللذاكرة: ffi.ذاكرة(حجم) وffi.حرر(مؤشر) وffi.اقرأ_نص(مؤشر, طول؟) وffi.اكتب_نص(مؤشر, نص).

قراءة وكتابة حقول الذاكرة (جديدة في 1.4.0): بدل قراءة البايتات يدوياً:

الدالة الوظيفة
ffi.اقرأ_حقل(مؤشر, إزاحة, نوع) يقرأ حقل من الذاكرة وفق النوع (i8 u8 i16 u16 i32 u32 i64 f32 f64) ويعيده رقماً
ffi.اكتب_حقل(مؤشر, إزاحة, نوع, قيمة) يكتب رقماً في الذاكرة وفق النوع (يخطئ على نوع غير معروف)
ffi.حجم_حقل(نوع) حجم النوع بالبايتات: ffi.حجم_حقل("i64") ← 8
استورد "ffi"
خل ذاكرة = ffi.ذاكرة(16)
ffi.اكتب_حقل(ذاكرة, 0, "i32", 42)
اطبع(ffi.اقرأ_حقل(ذاكرة, 0, "i32"))     // 42
اطبع(ffi.حجم_حقل("f64"))                 // 8

هذا يسهّل قراءة هياكل C: اقرأ كل حقل بإزاحته ونوعه بدل فك البايتات يدوياً.

القيود: x86-64 وAArch64 فقط، وحتى 6 وسائط صحيحة و8 عشرية، ولا float، ولا دوال متغيرة الوسائط (printf)، ولا استدعاءات راجعة (callbacks). تتطلب صلاحية اصلي، وهي أداة غير آمنة بطبيعتها.

11.2) كتابة وحدة أصلية (.so)

الواجهة في include/solan.h. وحدة صغيرة hello_native.c:

#include "solan.h"
#include <stdio.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;
}
static int squares(int argc, const SolanValue *argv, SolanValue *res, void *user) {
  (void)user; (void)argc;
  SolanValue l = solan_list_new(); int n = (int)solan_to_number(argv[0]);
  for (int i = 1; i <= n; i++) solan_list_push(l, solan_number((double)i * i));
  *res = l; return 0;
}
int solan_module_init(SolanModule *m) {
  solan_module_add_function(m, "جمع", add, 2, 2, NULL);        // (وحدة، اسم، دالة، أدنى وسائط، أقصى وسائط، بيانات مستخدم)
  solan_module_add_function(m, "مربعات", squares, 1, 1, NULL);
  solan_module_add_value(m, "الاصدار", solan_number(1));
  return 0;
}
cc -O2 -fPIC -shared -I include -o hello.so hello_native.c      # في مجلد المستودع
استورد "./hello.so"                 // الوحدة تُربط باسم الملف: hello
اطبع(hello.جمع(2, 3))               // 5
اطبع(hello.مربعات(4))                // [1، 4، 9، 16]
اطبع(hello.الاصدار)                  // 1

ملاحظات: ملف solan التنفيذي يصدّر دوال solan_* (علم -rdynamic عند البناء) لتجدها الوحدة وقت التحميل، فلا تربط وحدتك بـ libsolan ولا بالملف التنفيذي. تتطلب صلاحية اصلي. الدوال الرئيسية: الإنشاء (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).

11.3) تضمين سولان داخل برنامج C

ابنِ مكتبة مشتركة:

cc -O2 -fPIC -shared -DSOLAN_LIBRARY -Wno-format-truncation -o libsolan.so solan.c -lm -ldl

ثم:

#include "solan.h"
#include <stdio.h>
static int twice(int argc, const SolanValue *argv, SolanValue *res, void *user) {
  (void)argc; (void)user; *res = solan_number(2 * solan_to_number(argv[0])); return 0;
}
int main(void) {
  solan_init();
  solan_register_function("ضعف", twice, 1, 1, NULL);           // دالة عامة في سولان
  if (solan_eval("دالة مربع(س) { ارجع س * س }\nخل نتيجة = ضعف(21)", "demo")) {
    fprintf(stderr, "خطأ: %s\n", solan_last_error()); return 1;
  }
  SolanValue arg = solan_number(12), out;
  if (solan_call("مربع", 1, &arg, &out)) { fprintf(stderr, "خطأ: %s\n", solan_last_error()); return 1; }
  printf("مربع(12) = %g\n", solan_to_number(out));                // مربع(12) = 144
  return 0;
}
cc -I include -o demo demo.c -L. -lsolan -Wl,-rpath,.

وبقية الواجهة: solan_abi_version() وsolan_eval_file(path).


12) أدوات المحرر والتنسيق

  • التلوين في الطرفية: solan --لون ملف.سو. وكصفحة HTML: solan --html ملف.سو > out.html.
  • المنسّق: solan fmt ملف.سو -w (إزاحة وفراغات)، وsolan fmt ملف.سو --قياسي -w (مرادفات الكلمات المفتاحية إلى القياسية).
  • فحص الصياغة: solan --check ملف.سو.
  • المصحّح: solan --تصحيح ملف.سو للتنفيذ خطوة بخطوة، و--نقطة N لنقطة توقف.
  • خادم اللغة (LSP): solan lsp يعمل عبر stdio ويعطي أي محرر يدعم LSP إكمالاً وتشخيصاً (أخطاء صياغة).

13) البناء من المصدر

البناء

sh install.sh --build-only      # يبني ./solan بلا تثبيت (انظر القسم 1 لكل الخيارات)

يبني السكربت مباشرة بالمترجم ما يعادل:

cc -O2 -Wno-format-truncation -o solan solan.c -rdynamic -lm -ldl

أعلام الربط تتغير حسب المنصة (Linux/Android: -rdynamic -lm -ldl، macOS: -Wl,-export_dynamic -lm، BSD: -rdynamic -lm، Windows: -lm -lws2_32 -lshell32 -ladvapi32). علم التصدير لازم؛ بدونه تفشل الوحدات الأصلية بخطأ undefined symbol: solan_*. أعلام الترجمة الاختيارية عبر CFLAGS:

العلم الأثر
-DSOLAN_JIT=0 بلا المجمّع الفوري (الجيت يعمل افتراضياً على x86-64 Linux فقط)
-DSOLAN_FORK=0 بلا fork
-DSOLAN_NOPOOL بلا مجمّع الكائنات
-DSOLAN_LIBRARY يبني مكتبة مشتركة بدل ملف تنفيذي (القسم 11.3)

بناء نسخة ويندوز الأصلية

على ويندوز نفسه (بلا MSYS2 ولا WSL ولا بيئة لينكس) استعمل سكربتات النسخة الأصلية:

powershell -ExecutionPolicy Bypass -File pc\get-compiler.ps1          # مترجم MinGW محمول (مرة واحدة، ~264MB)
powershell -ExecutionPolicy Bypass -File pc\build-pc.ps1 -Installer   # بناء 64-بت + تشغيل الاختبارات + إنشاء المُثبِّت
  • ينتج dist\solan.exe ملفاً واحداً ثابتاً: -O3 + LTO، استهداف x86-64-v2 (SSE4.2 + POPCNT)، manifest بعلم activeCodePage=UTF-8 وlongPathAware، وأيقونة ومعلومات إصدار.
  • يفعّل الـJIT على ويندوز عبر طبقة VirtualAlloc/VirtualProtect، ويفعّل كومة الذاكرة منخفضة التجزؤ (LFH) عند الإقلاع.
  • الخيارات: -Arch32 (بناء 32-بت i686+SSE2 يعمل على ويندوز 32 و64 بت)، -V3 (استهداف AVX2 للأجهزة الحديثة)، -NoStrip (الاحتفاظ بالرموز للتنقيح)، -GccBin مسار (مترجم محدد).
  • المُثبِّت Solan-1.4.0-Setup-x64.exe يُبنى بـ Inno Setup بواجهة عربية كاملة (pc\installer.iss + pc\ArabicPC.isl): PATH + ربط ملفات .سو + إزالة تثبيت.
  • تعديلات المصدر الخاصة بويندوز كلها في src/platform/platform.inc وsrc/runtime/main.inc.

بنية المصدر

solan.c هو نقطة الدخول الوحيدة، ويضم بقية الملفات (.inc) في ترجمة واحدة:

المجلد المحتوى
src/compiler/ المحلل المعجمي والمترجم إلى بايتكود، والمفكك، وتلوين الكود
src/vm/ الآلة الافتراضية وطرق الأنواع (methods.inc) والوحدات (modules.inc) والمكتبة القياسية المضمَّنة (stdlib_embed.inc)
src/jit/ المجمّع الفوري: x86-64 (لينكس وويندوز) وARM64
src/core/ الأنواع وجامع المهملات والذاكرة
src/lib/ المكتبات الأصلية (ملفات، شبكة، JSON، regex، ضغط، قاعدة_سريعة، عميل TLS خالص + X.509، تشفير منحنيات، ffi، حزم، وقت، ضخم)
src/runtime/ نقطة التشغيل main.inc والـREPL وأدوات fmt وlsp وتهيئة الدوال المدمجة (init.inc)
src/abi/ واجهة C (capi.inc) وinclude/solan.h
src/platform/ الفروق بين الأنظمة (POSIX وويندوز: الذاكرة التنفيذية للـJIT، كومة LFH، UTF-8)
pc/ بناء نسخة ويندوز الأصلية: سكربت البناء build-pc.ps1 والمترجم المحمول والمُثبِّت وموارده (أيقونة، manifest، ترجمة عربية)
assets/ الهوية البصرية: البانر (solan-banner.jpg) والشعار الشفاف (solan-logo.png) وسكربت make-icons.ps1 الذي يولّد الأيقونات (شفافة) من البانر
dist/ النواتج الجاهزة بعد البناء (الملفات التنفيذية والمُثبِّت)

14) الاستقلالية والأداء والحدود المعروفة

ما الذي يحتاجه الملف التنفيذي فعلاً؟

الهدف: ملف واحد يعمل بلا تثبيت شيء.

الميزة المصدر تحتاج شيئاً من النظام؟
اللغة نفسها، VM، الجيت، جامع المهملات داخل المشروع لا (libc / libm فقط، ومعها libdl على Linux)
الضغط (gzip/zlib/deflate) وفك ردود HTTP المضغوطة داخل المشروع (flate.inc) لا
JSON، regex، BigInt، HTTP، WebSocket، المؤقتات داخل المشروع لا
TLS (https وwss وجلب_متدفق والبروكسي) عميل TLS خالص مضمّن — كل الاتصالات الصادرة لا
FFI والوحدات الأصلية dlopen بطبيعتها تعتمد على ما تحمّله أنت
  • الضغط: DEFLATE وzlib وgzip كاملة مع التحقق من CRC32 وAdler32 والطول، ودعم gzip متعدد الأعضاء، وسقف 512 ميغابايت للمخرجات ضد قنابل الضغط. حجم المخرجات قريب من zlib المستوى 6. الفك أبطأ من libz المُحسَّنة يدوياً، وكافٍ للاستعمال العادي.
  • TLS: عميل خالص مضمّن (TLS 1.3 وTLS 1.2) يعمل كل الاتصالات الصادرة (جلب وجلب_متدفق وwss والبروكسي) بلا أي مكتبة خارجية ولا أي مسار بديل.
  • التحقق بنفسك: solan -e 'اطبع(نظام.منصة())' يعرض ضغط_مضمن، وldd ./solan على Linux يريك المكتبات المربوطة.
  • لن يكون الملف ثابتاً بالكامل (-static) ما دمت تريد FFI والوحدات الأصلية وTLS، لأنها تعتمد على dlopen.

الأداء

الأداء يتفاوت حسب الجهاز وطبيعة البرنامج. الجيت يغطي الدوال العددية على x86-64 (لينكس وويندوز) وARM64، ولا يغطي الكائنات والدوال المجرّدة.

أرقام نسخة ويندوز الأصلية (نوفمبر 2026، نفس الجهاز):

القياس سولان بايثون Node.js
فيبوناتشي(27) عودي 37.4 م.ث 264.1 م.ث (أبطأ ×7.1) 95.0 م.ث (أبطأ ×2.5)
حلقة 10 مليون تكرار 66.6 م.ث — —
إقلاع + تشغيل برنامج صغير 22.7 م.ث ≈247 م.ث ≈110 م.ث

ملاحظة: نسخة بايثون على جهاز القياس هي مُطلِق متجر Windows (stub) فأرقامه تتضمن عبئاً إضافياً؛ القياس قابل لإعادة الإنتاج على أي جهاز.

الحدود المعروفة

  • المنصات: Linux وWindows وmacOS وBSD وAlpine وAndroid، مع اختلاف تفاصيل الربط حسب النظام.
  • اللغة:
    • الأرقام عشرية مزدوجة (دقة الأعداد الصحيحة حتى 2^53؛ للأكبر استعمل ضخم).
    • التفكيك لا يدعم الباقي ... (استعمله في المعاملات والقوائم والقواميس).
    • نسق لا يدعم فواصل الآلاف {:,} (استعمل عرض.ارقام_مفصولة).
    • لا نصوص بثلاث علامات اقتباس؛ النص العادي يمتد عبر الأسطر.
    • لا توجد كلمة export: كل تعريفات المستوى الأعلى عامة.
  • الحزم: التنزيل متسلسل، ولا توقيع رقمي (الأمان بالقفل والبصمة)، والحزم الثنائية لا تُختار حسب المنصة.
  • السوكت: القراءات الحاجبة (سطر واستقبل) توقف البرنامج؛ للخوادم استعمل حلقة.راقب أو شبكة.خادم_حلقة.
  • عميل TLS الخالص: HTTP/1.1 فقط (لا HTTP/2)، ولا استئناف جلسات ولا OCSP/CRL ولا mTLS؛ وخادم TLS غير مدعوم (تمرير شهادة/مفتاح يرمي خطأً).
  • العمليات الفرعية على ويندوز: نظام.فرع ونظام.عامل والدوال المرسلة لـعمال تُجمَّد مع البيئة العامة — كائنات الأصناف (صنف/واجهة) لا يمكن تجميدها؛ احذف تعريفات الأصناف من الملف أو أجّلها لدوال المصنع (رسالة الخطأ: تعذّر تجميد الدالة للعملية الفرعية). على لينكس/ماك (fork) القيد غير موجود.
  • الأنواع العامة: الفحص وقت التشغيل بعمق أقصى 8 مستويات، ولا تعمل على تعليقات الخصائص داخل الأصناف (على الدوال والمتغيرات فقط).
  • عدد_الى_حروف: صحيح من 0 إلى 999999 فقط؛ والكسور والأعداد الأكبر غير مدعومة.

15) ما الجديد: سجل الإضافات والتغييرات

الإصدار 1.4.0

إصدار لغوي شامل: أنواع عامة عميقة، واجهات، أخطاء منظمة، بنى بيانات جاهزة، أكثر من 40 طريقة جديدة على النصوص والقوائم والقواميس والأرقام، عمليات فرعية حقيقية على ويندوز، وتحسينات في الأداء والذاكرة. اجتازت اختبارات Windows (50/50) وJIT (6/6)، واختبار TCP loopback واختبار العمال المتوازيين.

اللغة

الإضافة التفصيل
أنواع عامة عميقة قائمة<رقم> وقاموس<نص, رقم> وقائمة<قائمة<رقم>> — الفحص وقت التشغيل يشمل العناصر (حتى عمق 8) وليس الحاوية فقط، ويتحقق القاموس من المفاتيح والقيم. رسالة الخطأ تحدد المواصفة كاملة: المعامل 'ق' يتوقع 'قائمة<رقم>' لكن وجدت 'قائمة'. تدعم حاوية القائمة نوع عنصر واحداً قد يكون اتحاداً مثل `قائمة<رقم
واجهات واجهة اسم { دالة ف() } تعرّف عقد طرق بلا أجسام (تُجمَّع تلقائياً)، ويطبق(كائن, واجهة) تفحص أسماء الطرق وتواقيع عدد/اختيارية المعاملات ونوع الطريقة (عادية/متبقية/getter/غير متزامنة/مولّدة) على الكائن أو الصنف؛ الأنواع المعلنة للوسائط والعودة توثيقية حالياً. كما تفحص هل_فرع(كائن, واجهة) التطبيق نفسه
تبديل بأنماط نوع حالة نص { ... } / حالة رقم / حالة منطقي... داخل تبديل (بتعليمة OP_TYPEIS المدمجة، ومطابقة في الجيت)
تبديل بنمط مدى حالة مدى(10, 20) تطابق القيم بين الطرفين شاملين (ضع الأنماط الأخص قبل حالة رقم لأنها تلتهم كل الأرقام)
صنف خطأ منظّم خطأ(رسالة, نوع = "مستخدم", سطر = 0, ملف = "") بحقول .رسالة .نوع .سطر .ملف .تتبع؛ وأخطاء النوع وقت التشغيل أصبحت تُرمى كائنات خطأ (نوعها "نوع")
تحذيرات المترجم علم جديد --تحذيرات (أو --warn) يظهر تحذيرات وقت الترجمة (متغيرات غير مستعملة، تظليل أسماء...)
ثبات الأنواع في الجيت حالة رقم ومدى في تبديل مدعومة في الجيت على x64 وARM64 بنفس دلالات المفسّر

اللغة: البنى الجاهزة الجديدة (prelude)

الإضافة التفصيل
اختياري صنف اختياري + بعض(ق) وفارغ_اختياري() وهل_اختياري(ق): .لديه_قيمة() .افتح() .او(بديل)، والنص بعض(5) / لا_شيء. افتح() على فارغ يرمي خطأ("فتح اختياري فارغ", "اختياري")
مجموعة (Set) مجموعة([عناصر؟]): .اضف (يسلسل) .يحتوي .احذف .حجم .فارغ .الى_قائمة .لكل .اتحاد .تقاطع .فرق، والنص مجموعة{1, 2}؛ .حجم و.فارغ خاصيتان
طابور طابور(): .اضف .اسحب (FIFO) .حجم .فارغ (خاصيتان)
مكدس مكدس(): .اضف .اسحب .قمة .حجم .فارغ (LIFO؛ الخاصيتان الأخيرتان)
نتيجة صنف نتيجة + جيد(ق) وفشل(خ) وهل_نتيجة(ق) — نمط النتيجة/الخطأ بلا استثناءات
من_ازواج من_ازواج([["أ", 1], ...]) — قاموس من قائمة أزواج
خطأ كصنف مسبّق صنف خطأ معرف دائماً (انظر الجدول أعلاه)

طرق جديدة على الأنواع (أكثر من 40 طريقة)

المجموعة الطرق
نصوص عربية .ازل_تشكيل() إزالة الحركات والتطويل · .طبّع() توحيد الهمزات والألف والياء والتاء المربوطة · .هل_عربي() · .عد_تشكيل()
نصوص عامة .املأ_وسط(عرض, حرف؟) توسيط · .عد_تطابق(ن) · .مواقع(ن) مواضع التطابقات غير المتداخلة بفهرسة Unicode (إزاحات تراكمية) · .قسم_متعدد(فواصل) تقسيم بعدة فواصل
قوائم تحويل .جمع_حسب(ف) · .عد_حسب(ف) · .فريد_حسب(ف) · .رتب_حسب(ف)
قوائم تقطيع .قسّم_قطع(ن) · .نوافذ(ن)
قوائم مسند .خذ_طالما(شرط) · .اترك_طالما(شرط) · .فريد_متتال()
قوائم تجميع .سطّح_كلي() كل المستويات · .اقترن_مع(قائمة, دالة_بوسيطين) · .اطوي_يسار(ف, بداية؟) · .تراكمي(ف, بداية؟) (الناتج يشمل قيمة البداية)
قواميس .حول_قيم(ف) · .رشح_مفاتيح(ف) · .اعكس_اتجاه() · .احصل_عميق(م1, م2, ...) (وسائط متعددة، يعيد عدم عند الغياب) · .اضبط_عميق(مسار, قيمة) (المسار قائمة) · .ادخل(م, ق) زوج
أرقام .قيمة_مطلقة() .أرضية() .سقف() .قرّب() .اقطع() .جذر() .هل_صحيح() .هل_غير_معرف() .هل_لانهائي() .عدد_الى_حروف() (0–999999 بالعربية) · .حول_ارقام_عربية() أرقام هندية

إدارة الذاكرة والجمع

الإضافة التفصيل
دوال القمامة اجمع_القمامة() (يشغّل جمعاً يدوياً ويعيد عدد الأحياء) · عدد_الكائنات() · حد_القمامة(حد؟) قراءة/ضبط العتبة
نمو ذكي للعتبة عتبة التجميع التالي تنمو ×4 بدل ×2 (حد أدنى 8192 كائناً) — تجميع أقل في البرامج الكبيرة
إصلاح تسريب صنف خطأ أصبح مُتعقّباً في جمع القمامة (كان يمكن أن يُحرَّر وهو مستعمل)

العمليات والتوازي (ويندوز)

الإضافة التفصيل
نظام.عملية على ويندوز تشغيل أوامر كعمليات فرعية بقنوات سوكت loopback ({مقبض, pid, دخل, خرج, خطأ}) — نفس عقد لينكس تماماً، وكل مقبض يعمل مع حلقة.راقب. كان سابقاً غير متاح على ويندوز إطلاقاً
نظام.فرع(دالة) على ويندوز عملية فرعية حقيقية بتجميد الدالة (globals + closure) في ملف مؤقت وتشغيل مفسر فرعي بوضع --عامل_فرعي. قيد موثق: لا كائنات أصناف في الدالة المجمّدة (خطأ تعذّر تجميد الدالة للعملية الفرعية)
نظام.عامل(دالة) على ويندوز عملية عاملة دائمة بقناة رسائل — أساس مكتبة عمال على ويندوز
إلغاء الوعود .ألغِ() · .عند_الغاء(ف) · .مع_مهلة(ث) · خاصية .ملغى (انظر 3.11)

التشفير وFFI

الإضافة التفصيل
إصلاح pbkdf2_sha256 الوسيط الرابع (طول المفتاح) كان يُقرأ خطأً فأعطى ناتجاً خاطئاً؛ الآن يقبل رقماً أو نصاً. النتائج مطابقة لمرجع Node.js crypto.pbkdf2Sync
تحسين pbkdf2_sha256 وسطية HMAC-SHA256 ثابتة تُبنى مرة واحدة: كل تكرار يحتاج كتلتَي SHA-256 بدل إعادة بناء HMAC كاملة (حتى أربع كتل وتخصيصات ذاكرة)
حقول ffi اقرأ_حقل(مؤشر, إزاحة, نوع) · اكتب_حقل(مؤشر, إزاحة, نوع, قيمة) · حجم_حقل(نوع) بأنواع i8 u8 i16 u16 i32 u32 i64 f32 f64 — قراءة هياكل C بلا فك بايتات يدوي (انظر 11.1)

التوزيع والتثبيت: مثبّتات فقط — لا حزم أرشيفية

البند التفصيل
إزالة النسخ الأرشيفية من الإصدارات لم تعد تُنشر نسخ zip (ويندوز) ولا tar.gz (لينكس/ماك) في صفحة Releases — كل منصة لها برنامج تثبيت أو حزمة نظام: ويندوز Setup.exe للمعماريات الثلاث، لينكس deb/rpm، ماك pkg
أمر تثبيت الخوادم (install-release.sh) أُعيد بناؤه: يكتشف النظام ومدير الحزم وينزّل الحزمة الأصلية ويُثبّتها — apt على دبيان/أوبونتو، dnf/yum/zypper على فيدورا/ريد هات/سوزي، installer على ماك؛ وعلى الأنظمة بلا مدير حزم (ألپاين، آرش...) يستخرج الملف التنفيذي الثابت من حزمة deb ويثبّته يدوياً (dpkg-deb -x أو فك ar + tar بأدوات النظام نفسها)
سير الإصدار (release.yml) حزم tar.gz للينكس أصبحت أرتيفكت نقل داخلي فقط (لمهمة بناء deb/rpm) ولا تُنشر؛ النشر 8 ملفات: 3 مثبّتات ويندوز + 2 deb + 2 rpm + pkg ماك (مع روابط تنزيل ثابتة لها)
روابط التنزيل في README جدول الأزرار يعرض المثبّتات وأمر التثبيت حصراً؛ حذف أقسام «النسخة المحمولة» من ويندوز ولينكس وماك وإعادة ترقيم بدائل البناء من المصدر

الطريقة القديمة → الطريقة الجديدة

الطريقة القديمة الطريقة الجديدة
فحص العناصر يدوياً بعد فحص الحاوية اكتب ق: قائمة<رقم> واترك الفحص للمُشغِّل
هل_فرع(ك, عقد) مع صنف فارغ للعقد واجهة عقد { ... } + يطبق(ك, عقد)
أخطاء نصية ثم تحليلها خطأ("رسالة", "نوع", سطر, ملف) وفحص .نوع مباشرة
هل_في(ق, س) بلا بنية مجموعة مجموعة مع .يحتوي بزمن ثابت
ق.رشح(...).قسّم... يدوياً .جمع_حسب .عد_حسب .قسّم_قطع .نوافذ جاهزة
حلقات اطوي متداخلة للتجميع .اطوي_يسار و.تراكمي صريحة وواضحة
قراءة هياكل C بفك بايتات ffi.اقرأ_حقل وffi.اكتب_حقل
لا إلغاء للوعود .ألغِ() و.مع_مهلة(ث) و.عند_الغاء(ف)

إزالات وتغييرات سلوكية

البند الحالة
حالة رقم في تبديل تطابق أي رقم (وليس الصحيح فقط) — إن كان كودك القديم يفترض صحةً فقط فاستعمل حالة عدد_صحيح أو ضع حالة مدى(...) قبله سلوك جديد
أخطاء النوع وقت التشغيل تُرمى كائنات خطأ بدل نصوص — كود يعتمد نص(خ) يبقى يعمل، وكود يقارن خ == "نص..." يحتاج تحديثاً إلى خ.رسالة سلوك جديد
عتبة جمع القمامة تنمو ×4 بدل ×2 أداء، بلا أثر واجهي

الإصدار 1.3.2

مثبّتات وحزم جاهزة لكل الأنظمة والمعماريات

البند التفصيل
ويندوز ARM64 بناء متقاطع جديد بـllvm-mingw: Solan-Setup-arm64.exe (مُثبِّت عربي كامل) وSolan-windows-arm64.zip — لأجهزة سطح ويندوز على ARM ولابتوبات ARM، والـJIT مفعّل
ويندوز 32-بت مثبّت Solan-Setup-x86.exe — المُثبِّت العربي أصبح متاحاً للمعمارية 32-بت أيضاً (سابقاً كان zip محمول فقط)
لينكس ARM64 حزم أصلية solan_1.3.2_arm64.deb وSolan-1.3.2-1.aarch64.rpm — حزم تثبيت نظام لأوبونتو/ديبيان وفيدورا/ريد هات على ARM64 (راسبيري باي 5، خوادم ARM)، تُبنى على عدّاء ARM أصلي
خيارات المُثبِّت محددة تلقائياً في كل تشغيل للمُثبِّت: أيقونة سطح المكتب + إضافة إلى PATH + ربط ملفات .سو كلها محددة افتراضياً؛ فقط «المسارات الطويلة» تبقى غير محددة (تحتاج صلاحيات مدير)
دعم معمارية المُثبِّت ملف installer.iss واحد يبني المُثبِّت للمعماريات الثلاث (x64/x86/ARM64) عبر /DArch مع فحص المعمارية عند التثبيت

ملاحظات:

  • إجمالي ملفات الإصدار الجاهز أصبح 17 ملفاً تغطي: ويندوز (3 مثبّتات + 3 محمول)، لينكس (2 ثابت + 2 deb + 2 rpm)، ماك (مثبّت pkg + محمول يونيفرسال) — كلها بلا أي مكتبات خارجية.
  • روابط التنزيل الثابتة في README وجدول المنصات تُحدّثت لتشمل الملفات الجديدة، وصفحة التثبيت في الموقع تعرضها كلها.
  • ترمكس (أندرويد) كما هو: بناء من المصدر بـsh install.sh بعد pkg install clang.

الإصدار 1.3.1

عميل TLS خالص من الصفر (بلا OpenSSL)

عميل TLS مكتوب بالكامل داخل المشروع (ملفات src/lib/tls13.inc وtls_net.inc وx509.inc وecbig.inc): يعمل شبكة.جلب على HTTPS حتى بلا OpenSSL نهائياً — وبنفس واجهة جلب كاملة (الرؤوس، الجسم، التحويلات، المهلة).

البند التفصيل
TLS 1.3 التشفيرات TLS_AES_128_GCM_SHA256 (0x1301) وTLS_CHACHA20_POLY1305_SHA256 (0x1303): HKDF كامل، تدوير مفاتيح، تحقق Finished، وkey_share بـ X25519 وP-256
TLS 1.2 (ثابت) المجموعتان 0x003C/0x003D (RSA-AES-CBC-SHA256 بمفاتيح 128/256) مع Extended Master Secret
TLS 1.2 (ECDHE) المجموعة ECDHE-RSA-AES128-SHA256 (0xC027): تحقق كامل من توقيع ServerKeyExchange (RSA-PKCS1 وRSA-PSS وECDSA)، ومنحنيات X25519 وP-256 وP-384، وحساب السر المشترك محلياً
الشهادات (X.509) تحليل ASN.1 وDER كامل، سلاسل الشهادات RSA وECDSA P-256/P-384، التحقق من الصلاحية الزمنية واسم المضيف (SAN وCN) والتوقيعات (RSA-PKCS1 وRSA-PSS وECDSA)
جذر الثقة الجذر الموثوق يأتي حصراً من: شهادات نظام التشغيل (مخزن ويندوز)، أو ملف SOLAN_CA_BUNDLE، أو خيار تحقق في جلب؛ الشهادة الموقعة ذاتياً في سلسلة الخادم لا تُعتبر جذر ثقة أبداً
التشفيرات المدمجة AES-GCM وAES-CBC وChaCha20-Poly1305 وSHA-256 وSHA-384 وHMAC وHKDF والمجمّعات المنحنية — كلها خالصة بلا مكتبات خارجية

ملاحظات:

  • ازالة OpenSSL نهائياً (تحديث لاحق في 1.3.1): حُذف مسار OpenSSL بالكامل من المصدر — لا dlopen لـ libssl ولا متغير SOLAN_LIBSSL ولا خيارات بصمة وتشفيرات وتشفيرات_13 ومجموعات وtls_ادنى وalpn. كل الاتصالات الصادرة (جلب وجلب_متدفق وwss والبروكسي) تعمل عبر العميل الخالص حصراً، ومسار curl الاحتياطي الخارجي حُذف أيضاً. تمرير شهادة/مفتاح لخادم TLS يرمي خطأً واضحاً (خادم TLS غير مدعوم)، وتمرير أي خيار من المحذوفين إلى جلب أو جلب_متدفق يرمي خطأً واضحاً يذكر الإزالة.
  • إزالة وحدة قاعدة (SQLite) نهائياً (تحديث لاحق في 1.3.1): حُذفت وحدة قاعدة التي كانت تحمّل مكتبة SQLite من النظام وقت التشغيل، مع كل ما يتعلق بها: ملف المصدر، والدوال (افتح نفذ استعلم نسخة دفعي اغلق)، والمرادفات، وحقل sqlite_مضمن من نظام.منصة()، وكل الإشارات في التوثيق والسكربتات. البديل المضمّن دائماً وبلا أي مكتبة خارجية هو المخزن السولاني قاعدة_سريعة (مكتوب بالكامل داخل المشروع — راجع القسم 5)، واسم قاعدة لم يعد محجوزاً.
  • تعطيل التحقق بـ تحقق: غلط متاح كالسابق.
  • تنظيف المُثبِّت والتوثيق: أُزيل اختصار «طرفية تفاعلية» من قائمة ابدأ في مُثبِّت ويندوز (لا حاجة له — التشغيل من أي طرفية بعد إضافة سولان إلى PATH)، وحُذفت من التوثيق كل أوامر تثبيت برامج مساعدة (winget/brew/apt/pkg) — لا شيء يحتاج تثبيتاً للعمل.

اختبارات

البند التفصيل
اختبار شامل ناجح TLS 1.3 ضد 5 مواقع حقيقية (نجاح=5 فشل=0)، وTLS 1.2 ضد خادم محلي في وضعي ECDHE وstatic-RSA، وbadssl للإصدار 1.2 حصراً، ورفض صحيح للشهادات المنتهية وذات الجذر الخاطئ
بناء نظيف tls13.inc وecbig.inc يُترجمان بلا أي تحذير حتى مع -Wall -Wextra؛ حُذف الكود الميت ووُحّدت المسارات المكررة في مسار ECDHE

توسعة المكتبات القياسية (تحديث لاحق في 1.3.1)

  • طرق جديدة للنصوص: فارغ موقع عد خذ اترك حرف_عند عنوان_حالة كبّر_اول نظف_يسار نظف_يمين هل_حرف_بالحرف.
  • طرق جديدة للقوائم: فارغ ادنى اعلى متوسط موقع عد خذ اترك اقترن اضف_الكل.
  • طرق جديدة للقواميس: فارغ اضبط_افتراضي دمج_جديد.
  • رياضيات: دوال وتر جذر_مكعب لوغ2 باقي علامة الى_درجات الى_راديان جيب_زائد جتا_زائد ظل_زائد، وثوابت لانهاية_سالبة نان باي_على_2 باي_على_4.
  • ضخم: دوال مطلق نفي القاسم_المشترك المضاعف_المشترك.
  • عشوائي: دوال بين عينة.
  • زمن: دوال الان_مللي منذ.
  • ملفات: دوال هل_ملف معلومات.
  • شبكة: دالة حلل_رابط.
  • جيسون: دالة هل_صالح.
  • نمط: دالة مجموعات (أسماء مجموعات الالتقاط المسمّاة).
  • تشفير: دوال crc32 pbkdf2_sha256.
  • ضغط: دوال فك_zlib خام فك_خام.
  • أرشيف: دالة يوجد، وأُضيف توثيق المكتبة كاملة إلى القسم 5.
  • مجموعات: دوال اتحاد تقاطع فرق_مجموعات على القوائم مباشرة.

الإصدار 1.2.0

إصلاحات

البند التفصيل
إصلاح ملفات.مسار_مطلق كانت تعيد عدم للمسارات غير الموجودة على القرص (لأنها اعتمدت realpath حصراً)؛ الآن تعيد المسار المطلق المطبَّع دائماً: ويندوز عبر _fullpath، وأنظمة يونكس عبر تطبيع نصي احتياطي (.. و. تُحلّ نصياً)
إصلاح UDP على ويندوز سوكت.ارسل_الى وسوكت.استقبل_من كانت تفشل دائماً بخطأ 10038 (WSAENOTSOCK) لأنها تُمرَّر فهرس جدول المقابض بدل مقبض السوكت نفسه؛ أُضيفت غلفة تحويل في طبقة توافق ويندوز
إصلاح تعليق شغل() بعد حلقة.اوقف() استدعاء حلقة.اوقف() ثم تشغيل كود غير متزامن (شغل) كان يعلّق البرنامج أبدياً: راية الإيقاف كانت تمنع إطلاق المؤقتات بينما تظل حلقة.خطوة() تبلّغ عن «تقدم» وهمي؛ الآن خطوة يصفّر الراية فيعمل غير المتزامن دائماً
رسالة خطأ UDP أوضح فشل ارسل_الى يعرض الآن رمز خطأ النظام (مثل فشل إرسال UDP (رمز الخطأ 10038)) بدل رسالة عامة

توثيق

البند التفصيل
تصحيح توثيق ضخم.رقم الدالة تعيد رقماً لا نصاً كما ورد سابقاً (ضخم.رقم("0042") = 42)

تعديلات لاحقة على 1.2.0

البند التفصيل
أزرار تنزيل مباشرة في التوثيق جدول أزرار إنجليزية (shields.io) في قسم التثبيت: ويندوز 64/32، ماك، لينكس 64/ARM64، deb/rpm — كل زر ينزّل أحدث إصدار مباشرة عبر روابط ثابتة بصيغة releases/latest/download/؛ سير الإصدار يرفع مع كل إصدار نسخاً بأسماء ثابتة بلا رقم إصدار لتبقى الروابط صالحة دائماً
إزالة إضافة VS Code من المشروع حُذف editor/vscode/ وسكربت بناء الحزمة وتكامل المُثبِّت معها؛ دعم المحررات يبقى كاملاً عبر solan lsp القياسي لأي محرر يدعم LSP (القسم 12). إضافة VS Code ستُنشر لاحقاً كحزمة مستقلة تُبحث وتُثبَّت من سوق الإضافات

الإصدار 1.1.0

دوال ومكتبات جديدة

الإضافة التفصيل
دوال رياضية عامة جذر قرب ارضي سقف بتر مطلق قوة لوغ اكبر اصغر متاحة مباشرة بلا استورد "رياضيات"
تشفير: SHA-512 sha512(نص) — بصمة 128 خانة، مدمجة بلا OpenSSL
تشفير: HMAC-SHA1 hmac_sha1(مفتاح, رسالة)
تشفير: Base64 للروابط base64_رابط(نص) — بلا حشو، بـ - و_، وbase64_قياسي اسماً صريحاً للقياسي
تشفير: X25519 x25519_سر · x25519_عام · x25519_مشترك — تبادل مفاتيح Diffie-Hellman وفق RFC 7748، تنفيذ خالص من الصفر (حقل 2^255-19 بأطراف 64-بت أساس 2^16)
تشفير: Ed25519 ed25519_سر · ed25519_عام · ed25519_وقّع · ed25519_تحقق — توقيع رقمي وفق RFC 8032 مع SHA-512 مدمجة ورفض S ≥ L
نظام.نفذ الموسعة نفذ(أمر, {دخل, مهلة, مجلد}) ← {رمز, ناتج, خطأ, انتهى_الوقت} مع إنهاء عند تجاوز المهلة
شبكة.جلب: بصمة TLS بصمة: "chrome" / "android" / "firefox" / "curl" — ClientHello كامل مطابق للمتصفحات (ALPN h2) (أُزيلت لاحقاً في 1.3.1 مع حذف مسار OpenSSL)
شبكة.جلب: بروكسي بروكسي: "socks5://..." أو "http://..." مع دعم user:pass@
شبكة.جلب: رؤوس_فقط رؤوس_فقط: صح — طلب HEAD يعيد الرؤوس بلا جسم
شبكة.جلب: تشفيرات تشفيرات: "..." — قائمة تشفيرات TLS صريحة (أُزيلت لاحقاً في 1.3.1 مع حذف مسار OpenSSL)
حزمة CA احتياطية مدمجة في الملف التنفيذي: HTTPS يعمل فوراً حتى بلا شهادات نظام

ويندوز (النسخة الأصلية الكاملة)

الإضافة التفصيل
JIT على ويندوز طبقة توافق VirtualAlloc/VirtualProtect تفعّل المجمّع الفوري على x64
كومة LFH تفعيل كومة الذاكرة منخفضة التجزؤ عند الإقلاع — أسرع للبرامج كثيفة الكائنات
بناء أصلي 100% بلا MSYS2 ولا WSL: مترجم MinGW محمول + pc\build-pc.ps1 (خيارات -Arch32 و-V3 و-Installer)
مُثبِّت عربي Solan-1.3.1-Setup-x64.exe بواجهة عربية كاملة: PATH + ربط ملفات .سو + إزالة تثبيت (في إصدار 1.3.1)
بناء 32-بت solan32 / -x86.zip — مفسَّر كامل الوظائف
UTF-8 والمسارات الطويلة manifest بعلم activeCodePage=UTF-8 وlongPathAware

أدوات وإصلاحات

البند التفصيل
JIT على ARM64 ترحيل المجمّع الفوري لتجميع الدوال على x86-64 وARM64 معاً
إصلاح HTTPS على ويندوز إصلاح مسار TLS وقت التشغيل على ويندوز
إصلاح الفهرسة مسار استدعاء (callout) للفهرسة العامة على المناطق المُجمَّعة بالـJIT

الرخصة: انظر ملف LICENSE. الأمان: انظر SECURITY.md.

About

سولان (Solan) — لغة برمجة عربية مفتوحة المصدر بمترجم أصلي، مكتبات قياسية متكاملة، وأدوات تطوير حديثة.

Topics

Resources

Security policy

Stars

4 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages