إنتقل إلى المحتوى الرئيسي

نظرة عامة على القواعد

يستخدم رمل قواعد ANTLR 4 مع محلل لغوي مخصص حساس للإزاحة. تصف هذه الصفحة البنية العامة لقواعد اللغة.


نظرة عامة​

كل برنامج رمل هو سلسلة من التعليمات:

program → statement* EOF

تبدأ البرامج عادةً التنفيذ عند الوسم :start:، رغم أنه يمكن استهداف أي وسم بواسطة jump.

أنواع التعليمات في لمحة​

الفئةالتعليماتالوصف
البنيةوسم القسم، القفزالوسوم (:name:) ونقل التحكم
الإعلاناتالنوع (كائن)، الدالة، الطريقة، المتغيرتعريف الأنواع، الدوال، الطرائق، المتغيرات
تدفق التحكمif/orif/else, while, switch/switchloop, try/catch/endالشرطيات، الحلقات، التفرع، معالجة الأخطاء
الحلقاتbreak, continueالتحكم في الحلقات
التعبيراتالإسناد، الثلاثي، استدعاء طريقة، استدعاء دالة، طباعةالحساب والإخراج
عمليات الحقولإسناد متعدد الحقول، التحقق من نطاق الحقولالتعامل مع حقول الكائنات

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

الفئةالكلمات المفتاحية
تدفق التحكمif, orif, else, while, break, continue
التفرعswitch, switchloop, case, default
معالجة الأخطاءtry, catch, end
القفزjump
الأنواعbs
الدوالfunctions, in
الإدخال/الإخراجprint

جميع الكلمات المفتاحية محجوزة ولا يمكن استخدامها كمُعرّفات. يمكن توطين جميع الكلمات المفتاحية عبر ملفات keywords.raml.lang.

الكتل والإزاحة​

تُعرَّف الكتل بالإزاحة:

block → INDENT statement+ DEDENT
  • نقطتان : يتبعهما سطر جديد وإزاحة أكبر تبدأ كتلة.
  • إزاحة أقل تنهي الكتلة الحالية.
  • الفواصل المنقوطة ; اختيارية ومفيدة بشكل أساسي للتعليمات أحادية السطر.

تفاصيل تقنية​

يغطي هذا القسم تفاصيل تنفيذ القواعد — المحلل المعجمي، بنية المحلل، معالجة الرموز، والأساس المنطقي للتصميم.

مستويات التعبيرات​

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

المستوى 1: expr (تعبيرات كاملة)​

قاعدة التعبير العليا. تتضمن جميع المعاملات:

  • الحسابية، البتية، الإزاحة
  • المقارنات (==, !=, <, >, <=, >=, =#=)
  • المنطقية (&&, ||)
  • استدعاءات الطرائق (->recv:method) والدوال وسلاسل الوصول
  • الزيادة/النقصان البادئة، عنوان، NOT بتية
  • التجميع بعلامتي قولون (::expr::)

تُستخدم في: الإسنادات، الشروط، حلقات while، شروط الثلاثي، التعبيرات المستقلة.

المستوى 2: exprItem (عناصر التعبير)​

مثل expr لكن مُهيكل كعناصر ضمن تعبيرات أكبر. يتضمن المقارنات والمعاملات المنطقية.

تُستخدم في: تعليمات الطباعة، قوائم تعبيرات الأنبوب.

المستوى 3: simpleExprItem (تعبيرات مقيدة)​

مجموعة فرعية مقيدة تستبعد معاملات المقارنة والمنطق:

  • مسموح: القيم، المتغيرات، سلاسل الوصول، الحسابية، البتية، الإزاحة، التجميع بعلامتي قولون، معاملات البادئة/اللاحقة
  • مستبعد: ==, !=, <, >, <=, >=, =#=, &&, ||

تُستخدم في: معاملات استدعاءات الطرائق والدوال، معاملات make.

لماذا هذا القيد؟ بدونه، ستُمتص المعاملات في قوائم المعاملات. مثلاً b:get move != 0 قد تُحلل كـ board_get(&b, move != 0) بدلاً من (board_get(&b, move)) != 0. انظر ملاحظات التصميم للسبب الكامل.

مرجع الرموز المعجمية​

الرمزالنمطالوصف
BSكلمة bsنوع تدفق البتات الديناميكي
IDحرف/شرطة سفلية + حروف/أرقام/شرطات سفليةمُعرّف (يدعم Unicode)
INTEGERعشري، 0x سداسي، أو 0b ثنائيقيمة عددية
STRINGعلامات اقتباس مفردة أو مزدوجة أو ثلاثيةقيمة سلسلة
ASSIGN=معامل الإسناد / قيمة صحيحة
ADDR#علامة عنوان/فك إشارة
ADDR_ASSIGN#=إسناد عنوان
ADDR_EQ=#=تساوي العناوين
DBL_COLON::تجميع بعلامتي قولون
DOTDOT..فاصل النطاق
ARROW->بادئة استدعاء الطريقة
AT@معامل العنوان
COLON:فاصل
SEMI;نهاية تعليمة
PIPE|تعبير الأنبوب
NL\n, \r, \r\nسطر جديد

المحلل المعجمي المخصص: معالجة الإزاحة​

يمد RamlCustomLexer.py محلل ANTLR المعجمي القياسي ليُصدر رموز INDENT/DEDENT:

  1. التحليل المعجمي: يُنتج المحلل المعجمي المولّد من ANTLR تدفقاً من الرموز القياسية.
  2. تتبع الإزاحة: قبل كل رمز، يتحقق المحلل المعجمي المخصص من مستوى إزاحة السطر الحالي.
  3. INDENT/DEDENT: إذا زادت الإزاحة، يُحقن رمز INDENT. إذا قلت، تُحقن رموز DEDENT واحدة لكل مستوى.
  4. حقن SEMI: يُحقن رمز SEMI (;) اختيارياً في نهاية أسطر التعليمات لدعم الفواصل المنقوطة الاختيارية.
  5. تصفية الأسطر الجديدة: تُدمج الأسطر الفارغة المتتالية.

المسندات في القواعد​

تستخدم القواعد مسندات ANTLR الدلالية لحل الغموض:

// منع وصول الحقل الديناميكي من استهلاك ':' كصياغة نوع
| ID COLON simpleExprItem COLON
{ self._input.LA(1) != self.ID && self._input.LA(1) != self.COLON }?

// منع تحليل استدعاءات الطرائق كإسنادات
methodCallStmt
: ARROW receiver ':' ID
{ self._input.LA(1) != self.ASSIGN && self._input.LA(1) != self.COLON }?
exprList

تُقيَّم هذه المسندات وقت التحليل وتُزيل الغموض بين بدائل القواعد المتعارضة دون الحاجة لإعادة هيكلة القواعد.

معالجة التعليقات​

ثلاثة أنماط تعليقات، جميعها تُتجاوز بواسطة المحلل المعجمي:

BLOCK_COMMENT : '/*' .*? '*/' -> skip;
COMMENT : '//' ~[\r\n]* -> skip;
ELIPSE_COMMENT : '…' [ \t]+ ~[\r\n]* -> skip;

تعليق النقاط (… نص) فريد في رمل — أي سطر يبدأ بـ … متبوعاً بمسافة يُعالج كتعليق. هذا مفيد لتعطيل الأسطر بسرعة أثناء التصحيح.

تنظيم ملف القواعد​

ملف القواعد (source/Raml.g4) مُنظم إلى:

  1. رموز المحلل المعجمي (الأسطر 1-80): تعريفات الكلمات المفتاحية، رموز المعاملات، أنماط القيم
  2. قواعد المحلل (الأسطر 82-النهاية): بنية البرنامج، الإعلانات، تدفق التحكم، التعبيرات
  3. قواعد fragment: قواعد مساعدة للمحلل المعجمي (مثل TRIPLE_DQUOTE)

مخرجات ANTLR المولَّدة:

الملفالغرض
RamlLexer.pyالمحلل المعجمي — يحول النص المصدر لتدفق رموز
RamlParser.pyالمحلل — يبني شجرة تحليل من تدفق الرموز
RamlVisitor.pyالزائر — فئة أساس مجردة لاجتياز AST
RamlListener.pyالمستمع — فئة أساس مجردة للتحليل المدفوع بالأحداث

انظر مرجع القواعد لملف القواعد ANTLR الكامل.