Domato 🍅

أداة فازنغ لـ DOM

كتبه ويشرف عليه Ivan Fratric، [email protected]

مرخّص بموجب رخصة Apache، الإصدار 2.0 (يُشار إليها فيما يلي باسم "الرخصة")؛ لا يجوز لك استخدام هذا الملف إلا امتثالاً للرخصة. يمكنك الحصول على نسخة من الرخصة على:

http://www.apache.org/licenses/LICENSE-2.0

ما لم يكن ذلك مطلوبًا بموجب القانون المعمول به أو متفقًا عليه كتابيًا، يتم توزيع البرنامج الموزَّع بموجب الرخصة على أساس "كما هو" (AS IS)، دون أي ضمانات أو شروط من أي نوع، سواء كانت صريحة أو ضمنية. راجع الرخصة للاطلاع على الصلاحيات والقيود المحددة التي تحكم الاستخدام.

الاستخدام

لعرض معلومات الاستخدام، نفّذ الأمر التالي:

python3 generator.py --help

لتوليد عيّنة .html واحدة، نفّذ:

python generator.py --file <output file>

لتوليد عيّنة .html واحدة باستخدام قالب كتبته بنفسك، نفّذ:

python generator.py --file <output file> --template <your custom template file>

لتوليد عيّنات متعددة باستدعاء واحد، نفّذ:

python generator.py --output_dir <output directory> --no_of_files <number of output files>

سيتم وضع العيّنات المولّدة في الدليل المحدد وستُسمى fuzz-<number>.html، مثل fuzz-00001.html و fuzz-00002.html وهكذا. يعد توليد عيّنات متعددة أسرع لأن ملفات القواعد تحتاج إلى التحميل والتحليل مرة واحدة فقط.

تنظيم الكود

يحتوي generator.py على النص البرمجي الرئيسي. يستخدم grammar.py كمكتبة ويحتوي على كود مساعد إضافي لفازنغ DOM.

يحتوي grammar.py على محرك التوليد الذي يكون في معظمه غير مرتبط بتطبيق معين، وبالتالي يمكن استخدامه في أدوات فازنغ أخرى قائمة على التوليد (أي غير مخصصة لـ DOM). ولأنه يمكن استخدامه كمكتبة، فقد تم وصف استخدامه في قسم منفصل أدناه.

تحتوي ملفات .txt على تعريفات القواعد. هناك 3 ملفات رئيسية، وهي html.txt و css.txt و js.txt، وتحتوي على قواعد HTML و CSS و JavaScript على الترتيب. وقد تتضمن ملفات القواعد الجذرية هذه محتوى من ملفات أخرى.

استخدام محرك التوليد وكتابة القواعد

لاستخدام محرك التوليد مع قواعد مخصصة، يمكنك استخدام كود Python التالي:

from grammar import Grammar

my_grammar = Grammar()
my_grammar.parse_from_file('input_file.txt')
result_string = my_grammar.generate_symbol('symbol_name')

تصف الأقسام التالية صيغة ملفات القواعد.

الصيغة الأساسية

يعتمد Domato على محرك يقوم، عند تزويده بقواعد خالية من السياق (context-free grammar) بصيغة بسيطة محددة أدناه، بتوليد عيّنات من تلك القواعد.

تُوصف القواعد النحوية على أنها مجموعة من القواعد الإنتاجية بالصيغة الأساسية التالية:

<symbol> = a mix of constants and <other_symbol>s

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

لننظر إلى المثال المبسّط التالي لجزء من قواعد CSS:

<cssrule> = <selector> { <declaration> }
<selector> = a
<selector> = b
<declaration> = width:100%

إذا طلبنا من محرك القواعد تحليل هذه القواعد وتوليد 'cssrule'، فقد نحصل في النهاية على أي من الناتجين:

a { width:100% }

أو

b { width:100% }

لاحظ وجود قاعدتين للرمز 'selector'. في مثل هذه الحالات، عندما يُطلب من المولّد توليد رمز 'selector'، سيختار القاعدة التي سيستخدمها بشكل عشوائي. ومن الممكن أيضًا تحديد احتمال القاعدة باستخدام الخاصية 'p'، على سبيل المثال:

<selector p=0.9> = a
<selector p=0.1> = b

في هذه الحالة، سيتم إخراج السلسلة 'a' بشكل أكثر تكرارًا من 'b'.

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

لننظر إلى مثال آخر لتوليد عيّنات html:

<html> = <lt>html<gt><head><body><lt>/html<gt>
<head> = <lt>head<gt>...<lt>/head<gt>
<body> = <lt>body<gt>...<lt>/body<gt>

لاحظ أنه بما أن '<' و '>' لهما معنى خاص في صيغة القواعد، فإننا نستخدم هنا <lt> و <gt> بدلاً منهما. هذه الرموز مدمجة في المحرك ولا تحتاج إلى تعريفها من قبل المستخدم. توجد قائمة بجميع الرموز المدمجة في قسم منفصل.

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

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

!varformat fuzzvar%05d
!lineguard try { <line> } catch(e) {}

!begin lines
<new element> = document.getElementById("<string min=97 max=122>");
<element>.doSomething();
!end lines

إذا طلبنا من المحرك توليد 5 أسطر، فقد نحصل في النهاية على شيء مثل:

try { var00001 = document.getElementById("hw"); } catch(e) {}
try { var00001.doSomething(); } catch(e) {}
try { var00002 = document.getElementById("feezcqbndf"); } catch(e) {}
try { var00002.doSomething(); } catch(e) {}
try { var00001.doSomething(); } catch(e) {}

لاحظ أن:

أسطر لغة البرمجة محاطة ببياني '!begin lines' و '!end lines'. يمنح هذا محلل القواعد المعلومات اللازمة بأن الأسطر الواقعة بينهما هي أسطر خاصة بلغة البرمجة، وبالتالي تُحلَّل بشكل مختلف.
استخدمنا <new element> بدلاً من <element>. يوجّه هذا المولّد إلى إنشاء متغير جديد من النوع 'element' بدلاً من توليد الرمز 'element'.
<string> هو أحد الرموز المدمجة، لذا لا حاجة لتعريفه.
[اختياري] يمكنك استخدام بيان !varformat لتحديد تنسيق المتغيرات التي تريد استخدامها.
[اختياري] يمكنك استخدام بيان !lineguard لتحديد كود إضافي يُدرج حول كل سطر بهدف التقاط الاستثناءات أو تنفيذ مهام أخرى. والهدف من ذلك هو ألا تضطر إلى كتابته لكل سطر على حدة.
بالإضافة إلى '!begin lines' و '!end lines'، يمكنك أيضًا استخدام '!begin helperlines' و '!end helperlines' لتحديد أسطر كود لا تُستخدم أبدًا إلا عند الحاجة إليها عند توليد أسطر أخرى (على سبيل المثال، قد تولّد الأسطر المساعدة متغيرات يحتاجها الكود 'الرئيسي'، لكنك لا تريد أبدًا أن تظهر هذه الأسطر المساعدة في المخرجات عندما لا تكون مطلوبة).

منع التكرار اللانهائي

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

!max_recursion 10
<test root=true> = <foobar>
<foobar> = foo<foobar>
<foobar nonrecursive> = bar

أولاً، يحدد بيان اختياري باسم ‘!max_recursion’ أقصى عمق للتكرار (50 افتراضيًا). لاحظ أن القاعدة الإنتاجية الثانية للرمز ‘foobar’ معلمة على أنها غير تكرارية. إذا تم بلوغ أقصى مستوى للتكرار في أي وقت، سيفرض المولّد استخدام القاعدة غير التكرارية للرمز ‘foobar’، مما يمنع التكرار اللانهائي.

تضمين واستيراد ملفات قواعد أخرى

في Domato، يعد تضمين القواعد واستيرادها سياقين مختلفين.

التضمين أبسط. يمكنك استخدام:

!include other.txt

لتضمين القواعد من other.txt في القواعد التي يتم تحليلها حاليًا.

أما الاستيراد فيعمل بشكل مختلف قليلاً:

!import other.txt

يخبر المحلل بإنشاء كائن Grammar() جديد يمكن الرجوع إليه من القواعد الحالية باستخدام الرمز الخاص <import>، على سبيل المثال كما يلي:

<cssrule> = <import from=css.txt symbol=rule>

يمكنك التفكير في الاستيراد والتضمين من منظور مساحات الأسماء (namespaces): سيضع بيان !include القواعد المضمّنة في مساحة الأسماء الموحدة، بينما ينشئ بيان !import مساحة أسماء جديدة يمكن الوصول إليها بعد ذلك باستخدام الرمز <import> ومساحة الأسماء المحددة عبر الخاصية 'from'.

تضمين كود Python

قد ترغب أحيانًا في استدعاء كود Python مخصص من داخل قواعدك. على سبيل المثال، لنفترض أنك تريد استخدام المحرك لتوليد استجابة HTTP وتريد أن يتطابق طول الجسم (body) مع ترويسة 'Size'. وبما أن هذا أمر غير ممكن باستخدام قواعد نحوية عادية، يمكنك تضمين كود Python مخصص لإنجازه كما يلي:

!begin function savesize
  context['size'] = ret_val
!end function

!begin function createbody
  n = int(context['size'])
  ret_val = 'a' * n
!end function

<foo root> = <header><cr><lf><body>
<header> = Size: <int min=1 max=20 beforeoutput=savesize>
<body> = <call function=createbody>

domato

الأكثر شعبية