Elsa

إلسا - محلل emacs lisp static

(الأميرة المفضلة لديك الآن في emacs!)

ELSA هي أداة تحلل الكود الخاص بك دون تحميله أو تشغيله. إنه خالي من التأثير الجانبي بنسبة 100 ٪ ونحن نسعى جاهدين للحفاظ على ذلك على هذا النحو ، حتى تتمكن من تحليل أي رمز ELISP من أي مكان بأمان.

تضيف ELSA نظامًا قويًا من النوع أعلى EMACS LISP (اختياري تمامًا). في CAN Track Trughs وتوفير تلميحات مفيدة عندما لا تتطابق الأمور قبل أن تحاول تشغيل الرمز.

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

• تحفيز
• حالة المشروع
• قائمة غير شاملة للميزات
  • اكتشف الكود الميت
  • فرض قواعد النمط
  • ابحث عن رمز مشبوه
  • أنواع التعبيرات المسار
  • فهم الحمولة الزائدة الوظيفية
• كيف يمكنني تشغيله
  • إيسك
  • برميل خشبي
  • بروتوكول خادم اللغة (LSP)
  • Makem.sh
  • إميك
  • Flycheck/Flymake Integration
• إعدادات
  • تمديد التحليل
  • قواعد
• اكتب التعليقات التوضيحية
• كيف يمكنني المساهمة في هذا المشروع
• التعليمات
  • ما الأمر مع الشعار؟
• للمطورين
  • كيف تكتب امتدادًا لمجموعة فافوريت
  • كيف تكتب مجموعة قواعد
• شكر وتقدير

تحفيز

لغات البرمجة الديناميكية ، مثل Emacs Lisp و JavaScript و Python ، لها العديد من المزايا على اللغات المكتوبة بشكل ثابت مثل Java أو C ++. إنها تسمح بتطوير أسرع ونماذج أولية بسبب طبيعتها الديناميكية ، مما يجعل من السهل الكتابة واختبار رمزها بسرعة.

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

ELSA هو نظام نوع ومحلل لـ EMACS LISP ، والذي يهدف إلى توفير فوائد نظام النوع مع الحفاظ على مرونة LISP والتعبير عنها. إنه مشابه لـ TypeScript لـ JavaScript أو Python type تلميحات للبيثون من حيث أنه يوفر طريقة لإضافة فحص نوع ثابت إلى لغة مطبوعة ديناميكيًا.

تحاول ELSA أن تكون منفاتًا واستخدام أكبر قدر ممكن من المعلومات المتاحة ، مثل إعلانات EDEBUG ، أو DEFMETHODERISTS أو أنواع الفصول الدراسية EIEIO ، وبالتالي يتم تقليل كمية التعليمات البرمجية التي يجب شرحها.

حالة المشروع

نحن حاليا في مرحلة بيتا . API ، نظام النوع والشروح مستقرون للغاية. نحن ندعم طرقًا متعددة لتثبيت المحلل وتشغيله.

تفتقر ELSA إلى الكثير من التعليقات التوضيحية للوظائف المدمجة (هناك حوالي 1500 منها) والمتغيرات. وبالتالي فإن نتائج التحليل لا تزال مثالية.

قد لا تزال الأمور تنكسر في أي وقت.

قائمة غير شاملة للميزات

هنا تأتي قائمة غير شاملة لبعض الميزات الأكثر إثارة للاهتمام.

يتم توفير تسليط الضوء على الأخطاء في لقطات الشاشة بواسطة Elsa Flycheck Extension.

كل ما تراه هنا يعمل في الواقع ، هذا ليس فقط للعرض!

اكتشف الكود الميت

اكتشف منطق المتفرعة المشبوهة

البحث عن رمز لا يمكن الوصول إليه في نماذج الدائرة القصيرة

فرض قواعد النمط

تقديم نصائح مفيدة لصنع كود منظف

أضف قواعد مخصصة لمشروعك مع قواعد القواعد

جعل التنسيق متسقا

ابحث عن رمز مشبوه

ابحث عن إشارات إلى المتغيرات الحرة/غير المقيدة

لا تخصص للمتغيرات الحرة

اكتشف الظروف التي تكون صحيحة أو خاطئة دائمًا

تأكد من تمرير الوظائف بما يكفي من الحجج

تأكد من عدم تمرير الوظائف الكثير من الحجج

أنواع التعبيرات المسار

تحقق من أنواع الوسائط التي تم تمريرها إلى وظائف التوافق

فهم النوع الذي يضيق من حراس النوع والمتنبئين

فهم الحمولة الزائدة الوظيفية

يمكن أن يأخذ downcase سلسلة وإرجاع سلسلة أو أخذ int وإرجاع int. نظرًا لأننا نمرر متغير سلسلة s ، يمكننا إزالة الغموض التي يجب استخدامها الزائد في الوظيفة ويمكننا استخلاص نوع الإرجاع للوظيفة string بدلاً من (or string int) .

إذا نجحنا في إدخال مدخلات لا تتطابق مع أي تحميل زائد ، فسوف تعرض ELSA تقريرًا مفيدًا عن الحمولة الزائدة المتاحة وما هي الوسيطة التي لم تتطابق معها.

كيف يمكنني تشغيله

يمكن تشغيل ELSA مع EASK أو CASK أو MAKEM.SH أو EMAKE. قبل أن تتمكن من إجراء التحليل ، راجع قسم التكوين حول كيفية تكوين المشروع.

يوفر مشروع ELSA الدعم لطرق EASK و CASK و LSP. للحصول على دعم makem.sh و emake ، اتصل بمؤلفي تلك الحزم مباشرة.

إذا كنت تستخدم EASK أو CASK ، فيمكنك استخدام تكامل Flycheck و Flymake (انظر أدناه).

بالإضافة إلى ذلك ، تقوم ELSA أيضًا بتنفيذ بروتوكول خادم اللغة (LSP) ويمكن استخدامه باستخدام وضع LSP. هذا هو الخيار الأفضل لأن جميع الحالة مخزنة مؤقتًا في الخادم وجميع العمليات سريعة جدًا. يعرض LSP أيضًا ميزات ELSA غير متوفرة ، مثل الإكمال (عبر lsp-completion-mode ) أو معلومات نوع التحوم بالسياق.

يلخص الجدول التالي الخيارات:

ميزة	إيسك	برميل خشبي	Makem.sh	إميك
تحليل مستقل من CLI	✓	✓	✓	✓
تكامل flycheck	✓	✓	⨯	⨯
دمج الذبذبات	✓	⨯	⨯	⨯
بروتوكول خادم اللغة (LSP)	✓	✓	⨯	⨯

ملاحظة: عندما تقوم بتشغيل ELSA في مشروع لأول مرة ، يوصى ببدءه من CLI لأنه سيحتاج إلى زحف جميع التبعيات التي تستخدمها وحفظ نتائج التحليل إلى ملفات ذاكرة التخزين المؤقت. قد يستغرق ذلك بضع دقائق إذا كان لديك العديد من التبعيات (أو إذا قمت بتضمين شيء مثل org الذي يسحب حوالي 300 حزمة أخرى).

بعد تخزين النتائج ، في المرة القادمة التي تحتاج إليها ، يمكن لـ ELSA تحميلها من ذاكرة التخزين المؤقت وهذا سريع جدًا بشكل عام.

يمكنك بدء LSP على الفور ولكن سيكون غير مستجيب خلال الوقت الذي تقوم به التحليل الأولي.

إيسك

[موصى به] باستخدام الإصدار المعبأ (عبر lint )

أسهل طريقة لتنفيذ إلسا مع إيسك:

 eask lint elsa [PATTERNS]

[PATTERNS] اختيارية ؛ الافتراضي سوف يرتب جميع ملفات الحزمة الخاصة بك.

[موصى به] باستخدام الإصدار المعبأ (عبر exec )

تستخدم هذه الطريقة EASK وتثبيت ELSA من MELPA.

1. إضافة (depends-on "elsa") إلى ملف Eask لمشروعك.
2. تشغيل eask install-deps .
3. eask exec elsa FILE-TO-ANALYSE [ANOTHER-FILE...] لتحليل الملف.

باستخدام إصدار التطوير (عبر exec )

لاستخدام إصدار تطوير ELSA ، يمكنك استنساخ المستودع واستخدام ميزة eask link لاستخدام الرمز من الاستنساخ.

1. git clone https://github.com/emacs-elsa/Elsa.git في مكان ما على جهاز الكمبيوتر الخاص بك.
2. إضافة (depends-on "elsa") إلى ملف Eask لمشروعك.
3. Run eask link add elsa <path-to-elsa-repo> .
4. eask exec elsa FILE-TO-ANALYSE [ANOTHER-FILE...] لتحليل الملف.

برميل خشبي

[موصى به] باستخدام النسخة المعبأة

تستخدم هذه الطريقة Cask وتثبيت Elsa من Melpa.

1. إضافة (depends-on "elsa") إلى ملف Cask لمشروعك.
2. تشغيل cask install .
3. cask exec elsa FILE-TO-ANALYSE [ANOTHER-FILE...] لتحليل الملف.

باستخدام إصدار التطوير

لاستخدام إصدار تطوير ELSA ، يمكنك استنساخ المستودع واستخدام ميزة cask link لاستخدام الرمز من Clone.

1. git clone https://github.com/emacs-elsa/Elsa.git في مكان ما على جهاز الكمبيوتر الخاص بك.
2. إضافة (depends-on "elsa") إلى ملف Cask لمشروعك.
3. قم بتشغيل cask link elsa <path-to-elsa-repo> .
4. cask exec elsa FILE-TO-ANALYSE [ANOTHER-FILE...] لتحليل الملف.

بروتوكول خادم اللغة (LSP)

يعمل تطبيق LSP الخاص بـ ELSA حاليًا ، لكن الخادم مستقر بدرجة كافية بحيث يكون من المفيد تشغيله. إنه يجعل التصعيد سريعًا للغاية ، لأن كل الحالة يتم تخزينها مؤقتًا في مثيل الخادم ولا يتعين علينا إعادة قراءة ذاكرة التخزين المؤقت بأكملها تمامًا من نقطة الصفر (مثل الركض عبر Flycheck أو Flymake).

تدعم ELSA حاليًا وضع LSP ، ولكنه لم يتم دمجه بعد في وضع LSP نفسه لأنه (ELSA LSP) غير مستقر بدرجة كافية. لاستخدام ELSA LSP ، قم بتشغيل (elsa-lsp-register) أو Mx elsa-lsp-register لتسجيل العميل مع lsp-mode . بعد ذلك ، سيبدأ استخدام Mx lsp في المخزن المؤقت ELISP مساحة عمل.

حاليًا ، يتم دعم إمكانيات LSP هذه

القدرة	مُنفّذ
Hoverprovider	يوفر التعليقات التوضيحية نوع سياق النماذج تحت النقطة
TextDocumentSync	openclose ، حفظ
الانتهاء	وظائف من مساحة العمل المتغيرات من النطاق ومساحة العمل قرار خاص لأسماء فتحات OREF/OSET

Makem.sh

باستخدام makem.sh ، ما عليك سوى تشغيل هذا الأمر من دليل جذر المشروع ، والذي يقوم بتثبيت ويدير Elsa في صندوق رمل مؤقت:

 ./makem.sh --sandbox lint-elsa

لاستخدام دليل صندوق رمل غير مؤقت يدعى .sandbox وتجنب تثبيت ELSA على كل تشغيل:

1. ./makem.sh -s.sandbox --install-deps --install-linters صندوق الرمل:.
2. Run Elsa: ./makem.sh -s.sandbox lint-elsa .

انظر وثائق makem.sh لمزيد من المعلومات.

إميك

إذا كنت قد قمت بتثبيت Emake بالفعل ، فاستمر في تشغيل make lint-elsa . قد تحتاج إلى التحديث إلى إصدار حديث عبر EMAKE_SHA1 .

خلاف ذلك ، قم بتثبيت Emake عبر الوسائل المعتادة:

bash <( curl -fsSL https://raw.githubusercontent.com/vermiculus/emake.el/master/new )

سيطالبك هذا البرنامج النصي لاسم الحزمة الخاصة بك ثم bootstrap emake. يمكنك الآن تشغيل شيكات Elsa باستخدام make lint-elsa .

Flycheck/Flymake Integration

إذا كنت تستخدم flycheck ، فيمكنك استخدام حزمة flycheck-elsa التي تدمج Elsa مع Flycheck.

ل flymake ، يمكنك استخدام flymake-elsa.

إعدادات

في الوقت الحالي ، تدعم ELSA تكوينًا قليلًا جدًا. إلى "Elsa-cenable" مشروعك ، يجب عليك إضافة Elsafile.el إلى جذر مشروعك.

لدى ELSA مفهوم الإضافات والقواعد ، والتي توجد حاليًا في الغالب داخليًا وملفوفة في مجموعة قواعد وامتداد "افتراضية" واحدة كبيرة. هذا النظام لا يزال يعمل قيد التقدم.

فيما يلي بعض الطرق التي يمكنك من خلالها تمديد إلسا اليوم.

تمديد التحليل

تتمثل إحدى طرق تمديد ELSA في توفير قواعد تحليل خاصة لمزيد من الأشكال والوظائف حيث يمكننا استغلال معرفة كيفية تصرف الوظيفة لتضييق التحليل لأسفل.

على سبيل المثال ، يمكننا أن نقول أنه إذا not تكن مدخلات t ، فإن قيمة الإرجاع تكون دائمًا nil . هذا يشفر معرفتنا المجال في شكل قاعدة تحليل.

تتم إضافة جميع القواعد في شكل امتدادات. لدى ELSA عدد قليل من الامتدادات الأساسية لأكثر الوظائف المدمجة شيوعًا مثل معالجة القائمة ( car ، nth ...) ، المتنبئين ( stringp ، atomp ...) ، وظائف منطقية ( not ، ...) وما إلى ذلك. يتم تحميلها تلقائيًا لأن الوظائف شائعة جدًا تقريبًا كل مشروع سيستخدمه.

يتم توفير امتدادات إضافية للحزم الخارجية الشهيرة مثل Dash.el. لاستخدامها ، أضف إلى نموذج Elsafile.el من نموذج register-extensions ، مثل ذلك

(register-extensions
 dash
 ; ; more extensions here
 )

يتم تحميل الامتدادات تلقائيًا عندما تأتي ELSA على نموذج يتطلب. من أجل (require 'foo) ، سوف يبحث عن elsa-extension-foo.el ويحاول تحميله. هذا يعني أنه في الممارسة العملية لن تضطر أبدًا إلى تسجيل ملحقات لمعظم حزم الطرف الثالث.

قواعد

بعد تحليل النماذج ، لدينا جميع المعلومات النوعية و AST جاهزة لمزيد من معالجتها بواسطة مختلف الشيكات والقواعد.

يمكن أن تكون هذه (قائمة غير شاملة):

• الأسلوب ، مثل التحقق من أن المتغير يستخدم lisp-case لتسمية بدلاً من snake_case .
• النحوية ، مثل التحقق من أننا لا نلف الفرع الآخر if مع progn غير المجدية.
• الدلالي ، مثل التحقق من أن حالة ما if لم يتم تقييمه دائمًا إلى non-nil (وفي هذه الحالة يكون النموذج if عديم الفائدة).

توفر ELSA بعض القواعد المدمجة ويمكن أيضًا استخدام المزيد من خلال تحميل الامتدادات.

لتسجيل مجموعة قواعد ، أضف النموذج التالي إلى Elsafile.el

(register-ruleset
 dead-code
 style
 ; ; more rulesets here
 )

اكتب التعليقات التوضيحية

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

اقرأ وثائق نوع التعليقات التوضيحية لمزيد من المعلومات حول كيفية كتابة أنواعك الخاصة.

كيف يمكنني المساهمة في هذا المشروع

افتح مشكلة إذا كنت ترغب في العمل على شيء ما (غير مدرج بالضرورة أدناه في خريطة الطريق) لذلك لن نكرر العمل. أو فقط أعطنا ملاحظات أو نصائح مفيدة.

يمكنك توفير تعريفات النوع للوظائف المدمجة عن طريق توسيع elsa-typed-builtin.el . هناك الكثير للذهاب. قد لا توجد أو دعم بعض الأنواع اللازمة للتعبير عن ما نريده بعد ، حتى نتمكن من مناقشة كيفية تصميم الأشياء.

التعليمات

ما الأمر مع الشعار؟

انظر المناقشة.

للمطورين

بعد الاتصال (require 'elsa-font-lock) هناك وظيفة elsa-setup-font-lock التي يمكن استدعاؤها من emacs-lisp-mode-hook لإعداد بعض خطوط الخطوط الإضافية لأنواع ELSA.

كيف تكتب امتدادًا لمجموعة فافوريت

كيف تكتب مجموعة قواعد

شكر وتقدير

كان أكبر مصدر إلهام هو مشروع Phpstan ، الذي وفر لي الدافع الأولي لبدء هذا المشروع. لقد مررت بمصادرهم عدة مرات في العثور على الإلهام واختيار الميزات.

الإلهام الثاني هو TypeScript ، الذي حول لغة غير مهتمة إلى حد ما إلى قوة على شبكة الإنترنت (ليس فقط).

أستعير بشدة من هذين المشروعين وأوسع امتناني وإعجابي.