moonpick

مونبيك

ما هذا؟

Moonpick هو أداة بديلة لـ Moonscript. على الرغم من أن Moonscript يأتي مزودًا بوحدة قياس مدمجة، إلا أنه محدود حاليًا فيما يمكنه اكتشافه. على سبيل المثال، سوف يكتشف جهاز linter المدمج المتغيرات غير المستخدمة، ولكن فقط لمجموعة فرعية من جميع الإعلانات غير المستخدمة المحتملة. لن يكتشف متغيرات الاستيراد غير المستخدمة، ومتغيرات التحليل، والوظائف غير المستخدمة، وما إلى ذلك. وُلد Moonpick في محاولة لاكتشاف ما ورد أعلاه والمزيد.

التثبيت والاستخدام

يمكن تثبيت Moonpick عبر Luarocks:

 $ luarocks install moonpick

ويمكن بعد ذلك تشغيله من سطر الأوامر:

$ moonpick < path-to-file >

يحاكي الإخراج بشكل وثيق إخراج الوبر المدمج في Moonscript.

كما يتم تجميعه بسهولة في تطبيق مستقل نظرًا لأن اعتماده الوحيد هو Moonscript. راجع قسم API لمزيد من المعلومات حول كيفية تشغيله برمجياً.

ماذا يكشف؟

المتغيرات غير المستخدمة

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

معلمات الوظائف غير المستخدمة

يمكن لـ Moonpick أيضًا اكتشاف معلمات الوظائف المعلنة ولكن غير المستخدمة والشكوى منها. لا يتم تمكين هذا افتراضيًا، لأنه من الشائع جدًا وجود معلمات غير مستخدمة. على سبيل المثال، قد تتبع إحدى الوظائف واجهة برمجة تطبيقات خارجية وتظل ترغب في الإشارة إلى المعلمات المتاحة على الرغم من عدم استخدام جميعها. لتمكين هذا، قم بتعيين خيار التكوين report_params على true .

يأتي Moonpick مزودًا بتكوين افتراضي يقوم بإدراج أي معلمة تبدأ بـ '_' في القائمة البيضاء، مما يوفر طريقة للحفاظ على الجوانب التوثيقية لوظيفة ما مع الاستمرار في إرضاء المستخدم.

متغيرات الحلقة غير المستخدمة

تم الكشف عن متغيرات الحلقة غير المستخدمة. من الممكن تعطيل هذا تمامًا في التكوين، أو توفير قائمة بيضاء واضحة لمتغيرات الحلقة فقط. يأتي Moonpick بتكوين افتراضي يدرج الوسيطتين 'i' و'j' في القائمة البيضاء، أو أي متغير يبدأ بـ '_'.

وصول عالمي غير محدد

على غرار جهاز linter المدمج، يكتشف Moonpick مراجع غير محددة.

تظليل الإعلان

يحدث تظليل الإعلان عندما يقوم إعلان بتظليل إعلان سابق يحمل نفس الاسم. خذ بعين الاعتبار الكود التالي:

my_mod = require ' my_mod '

-- [.. more code in between.. ]

for my_mod in get_modules ( ' foo ' )
  my_mod . bar!

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

يمكن إيقاف تشغيل الكشف تمامًا عن طريق تعيين متغير التكوين report_shadowing على false، ويمكن تكوين القائمة البيضاء عن طريق تحديد قائمة تكوين whitelist_shadowing .

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

إعادة تعيين المتغيرات الوظيفية

نادرًا ما تكون إعادة تعيين متغير محدد مسبقًا يحمل قيمة دالة أمرًا مطلوبًا، وغالبًا ما يكون ذلك نتيجة لنسيان إعلان سابق.

 -- with the following declaration and usage
done = ( x ) -> x . foo and x . bar
done ( {} )

-- one might mistakenly reuse the name further down
i = 1
-- [..]
done = i == 10

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

يمكن إيقاف تشغيل الكشف تمامًا عن طريق تعيين متغير التكوين report_fndef_reassignments على false، ويمكن تكوين القائمة البيضاء عن طريق تحديد قائمة تكوين whitelist_fndef_reassignments .

إعادة تعيين متغيرات المستوى الأعلى من دالة أو طريقة

يمكن أن تكون إعادة تعيين متغير المستوى الأعلى من داخل وظيفة أو طريقة في بعض الأحيان سببًا لأخطاء غير واضحة ومراوغة، على سبيل المثال:

 module = require ' lib.module '

-- [..] much further down
get_foo = ( y ) ->
  module = y  match ( ' %w+ ' )  lower! -- mistakenly reusing the `module` var
  return " #{module}_bar "

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

وعلى النقيض من الاكتشافات الأخرى، لا يتم تمكين هذا الكشف بشكل افتراضي. يمكن تشغيل الكشف عن طريق تعيين متغير التكوين report_top_level_reassignments على true، ويمكن تكوين القائمة البيضاء عن طريق تحديد قائمة تكوين whitelist_top_level_reassignments . ومع ذلك، يوصى بشدة بتمكين هذا.

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

إعدادات

يدعم Moonpick مجموعة فائقة من نفس ملف التكوين والتنسيق مثل جهاز linter المدمج.

وهو يوفر خيارات تكوين إضافية عن طريق إضافة دعم لتكوين فحص معلمات الوظائف ومتغيرات الحلقة، كما يسمح أيضًا بأنماط Lua في جميع القوائم البيضاء. يمكن كتابة ملفات تكوين Linter إما بلغة Lua أو Moonscript ( lint_config.lua و lint_config.moon على التوالي).

انظر المثال أدناه (lint_config.moon، باستخدام بناء جملة Moonscript):

 {
  whitelist_globals : {
    -- whitelist for all files
    [ " . " ] : { ' always_ignore ' } ,

    -- whitelist for files matching 'spec'
    spec : { ' test_helper ' } ,
  }

  whitelist_params : {
    -- whitelist params for all files
    [ " . " ] : { ' my_param ' } ,

    -- ignore unused param for files in api
    api : { ' extra_info ' } ,
  }

  whitelist_loop_variables : {
    -- always allow loop variables 'i', 'j', 'k', as well as any
    -- variable starting with '_' (using a Lua pattern)
    [ " . " ] : { ' i ' , ' j ' , ' k ' , ' ^_ ' } ,
  }

  -- general whitelist for unused variables if desired for
  -- some reason
  whitelist_unused : {
    [ " . " ] : {} ,
  }

  -- below you'll see the boolean switches controlling the
  -- linting, shown with the default value

  -- report_loop_variables: true
  -- report_params: true
  -- report_shadowing: true
  -- report_fndef_reassignments: true
  -- report_top_level_reassignments: false
}

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

واجهة برمجة التطبيقات

com.moonpick

 local moonpick = require ( ' moonpick ' )

لينت (الكود، التكوين = {})

يقوم بفحص الكود المحدد في code ، ويعيد جدول عمليات فحص الفحص. config هو تكوين الفحص الذي سيتم استخدامه للملف، ويمكن أن يحتوي على إصدارات مسطحة من العناصر الموجودة عادةً في ملف التكوين ( whitelist_globals ، whitelist_params ، whitelist_loop_variables ، whitelist_unused ، report_params ، report_loop_variables ).

مثال لجدول التكوين (بناء جملة Lua):

 local moonpick = require ( ' moonpick ' )
local code = ' a = 2 '
moonpick . lint ( code , {
  whitelist_globals = { ' foo ' , ' bar ' , }
  whitelist_params = { ' ^_+ ' , ' other_+ ' }
})

سيبدو جدول عمليات الفحص المرتجعة كما يلي في المثال أعلاه:

{
  {
    line = 1 ,
    pos = 1 ,
    msg = ' declared but unused - `a` ' ,
    code = ' a = 2 '
  }
}

lint_file(ملف، يختار = {})

فحص file المحدد، وإرجاع جدول عمليات فحص الفحص. يمكن أن تحتوي opts حاليًا على قيمة واحدة، lint_config ، والتي تحدد ملف التكوين الذي سيتم تحميل التكوين منه.

moonpick.config

 local moonpick_config = require ( ' moonpick.config ' )

التكوين_ل(المسار)

يُرجع مسار ملف التكوين ذي الصلة path ، أو nil إذا لم يتم العثور على أي شيء.

Load_config_from(config_path، ملف)

يقوم بتحميل تكوين الفحص file الملف من ملف التكوين المقدم بواسطة config_path . سيكون التكوين الذي تم إرجاعه عبارة عن جدول خيارات تكوين مسطح file .

مقيم (التكوين)

إرجاع نسخة مقيّمة لخيارات الفحص المحددة (على سبيل المثال، كما تم إرجاعها بواسطة load_config_from ). يوفر مثيل المقيم الوظائف التالية (لاحظ أن هذه وظائف، سيتم استدعاؤها باستخدام عامل النقطة العادي . ):

allow_global_access ، allow_unused_param ، allow_unused_loop_variable ، و allow_unused ، allow_fndef_reassignment ، و allow_top_level_reassignment .

كل هذه العناصر تأخذ رمزًا (كسلسلة) كوسيطة أولى وترجع true أو false اعتمادًا على ما إذا كان الرمز يمر بعملية الفحص أم لا.

الوضع الحالي

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

رخصة

حقوق الطبع والنشر 2016-2017 نيلز نوردمان

تم إصدار Moonpick بموجب ترخيص MIT (راجع ملف الترخيص للحصول على التفاصيل الكاملة).

تشغيل المواصفات

تتطلب الاختبارات busted للتشغيل، بالإضافة إلى وحدة pl (Penlight - luarock install penlight ). فقط قم بتشغيل busted في الدليل الجذر للمشروع.

تشغيله محليا لأغراض التنمية

يتم التنفيذ باستخدام LUA_PATH محدد يشير إلى دليل src المحلي. بافتراض موقع الخروج ~/code/moonpick :

LUA_PATH= " $HOME /code/moonpick/src/?.lua; $HOME /code/moonpick/src/?/init.lua; $( lua -e ' print(package.path) ' ) " ~ /code/moonpick/bin/moonpick * .moon