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

مرجع القواعد

مرجع قواعد ANTLR الكامل لـ رمل، مُنظم حسب الفئة. المصدر: source/Raml.g4.


نظرة عامة​

تحتوي هذه الصفحة على قواعد ANTLR الكاملة بشكلها الخام. يعرض كل قسم قواعد المحلل والمحلل المعجمي الكاملة لميزة لغة معينة.

كيفية قراءة صياغة ANTLR:

الترميزالمعنى
rule : ... ;تعريف قاعدة محلل
TOKEN : ... ;تعريف رمز محلل معجمي
|بديل (أو)
?اختياري (0 أو 1)
*صفر أو أكثر
+واحد أو أكثر
{ ... }?مسند دلالي (شرط وقت التشغيل)
-> skipتخطي الرمز في المحلل المعجمي

للحصول على نظرة عامة عالية المستوى لبنية القواعد، انظر نظرة عامة على القواعد.


البرنامج والتعليمات​

program
: statement* EOF
;

statement
: sectionLabel
| jumpStmt
| typeDecl
| functionDecl
| methodDecl
| methodCallStmt
| printStmt
| assignment
| varDecl
| functionCallStmt
| ifStmt
| switchStmt
| whileStmt
| tryFailStmt
| breakStmt
| continueStmt
| ternaryStmt
| paramDecl
| rangeFieldCheck
| expr
| SEMI
;

وسوم الأقسام والقفز​

sectionLabel
: ':' labelName ':' block? # sectionDecl
;

jumpStmt
: JUMP ':' labelName ':' # jumpSection
;

labelName
: ID INTEGER?
;

الوسوم تكتب كـ :name: ويمكن أن تتضمن رقماً اختيارياً (مثل :phase1:). jump ينقل التحكم إلى وسم.

إعلانات الكائنات​

typeDecl
: ID COLON structBlock # structDecl
;

structBlock
: INDENT structItemOrSemi+ DEDENT
;

structItemOrSemi
: structItem
| SEMI
;

structItem
: fieldDecl
| functionsBlock
;

الكائنات تُعرّف بـ name: متبوعة بكتلة مُزاحة من الحقول وقسم functions:.

إعلانات الحقول​

fieldDecl
: fieldSpec fieldSpec* NL? # fieldDeclList
;

fieldSpec
: typeSpec nameList # fieldTypeGroup
| ID typeSpec # fieldNameTyped
| ID COLON typeSpec # fieldNameColon
| ID COLON indentedNestedStruct # fieldNestedIndented
| ID COLON inlineNestedStruct # fieldNestedInline
;

nameList
: ID ID*
;

typeSpec
: bsType
| ID // named type reference (bs, struct names, etc.)
| typeSpec '#'
;

الحقول تدعم أنماط إعلان متعددة:

  • مجموعة: flags code
  • مُنوعة النوع: flags bs
  • بنقطتين: flags: bs
  • كائن متداخل (مزاح): meta:\n flags
  • كائن متداخل (مضمن): meta: flags code

الكائنات المتداخلة​

indentedNestedStruct
: INDENT nestedFieldOrSemi+ DEDENT
;

nestedFieldOrSemi
: nestedField
| SEMI
;

nestedField
: fieldDecl
;

inlineNestedStruct
: fieldDecl fieldDecl* NL?
;

أنواع البتات​

bsType
: BS
;

الدوال والطرائق​

functionDecl
: ID COLON functionBlock # functionDefinition
;

functionBlock
: INDENT paramDecl statement* DEDENT
;

methodDecl
: typeName=ID COLON methodName COLON block # methodDefinition
;

methodName
: ID
;

paramDecl
: IN COLON paramSpecList?
;

paramSpecList
: paramSpec paramSpec*
;

paramSpec
: bsType ID
| ID
;

الدوال تُعرّف ضمن كتلة functions: للكائن:

functionItem
: methodName # functionDeclOnly
| methodName COLON block # functionDefBlock
| methodName COLON inlineStatement # functionDefInline
;

functionItemOrSemi
: functionItem
| SEMI
;

functionsBlock
: FUNCTIONS COLON INDENT functionItemOrSemi+ DEDENT
;

التعليمات المضمنة (أجسام دوال أحادية السطر):

inlineStatement
: assignment
| methodCallStmt
| functionCallStmt
| printStmt
| expr
;

المتغيرات والإسنادات​

varDecl
: typeSpec nameList ASSIGN expr # varDeclTypedLeading
| typeSpec nameList # varDeclTypedNoInit
| ID COLON typeSpec ASSIGN expr # varDeclTyped
| ID COLON typeSpec # varDeclTypedNoInitColon
| ID COLON expr # varDeclInferred
;

assignment
: accessChain ASSIGN expr # assignNormal
| accessChain ADDR_ASSIGN expr # assignADDR
| accessChain compoundOp expr # assignCompound
| COLON nameList COLON ASSIGN expr # assignMultiField
;

compoundOp
: '+=' | '-=' | '*=' | '/=' | '%='
| '&=' | '|=' | '^=' | '<<=' | '>>='
| '+#=' // bit increment
;

الوصول الديناميكي للحقول​

primaryAccess
: ID # primaryAccessId
| ID COLON INTEGER COLON # dynamicFieldAccess
| ID COLON simpleExprItem COLON { self._input.LA(1) != self.ID and self._input.LA(1) != self.COLON }? # dynamicFieldAccessExpr
| ADDR accessChain # primaryAccessAddr
;

الوصول الديناميكي للحقول يسمح بالوصول إلى حقل كائن أو متغير عام يُحدد اسمه أثناء التنفيذ:

  • c:1: — فهرس حرفي، يحل إلى الحقل c1
  • c:idx: — فهرس تعبيري، يحل idx إلى اسم حقل مثل c1، c2، إلخ.
  • يُستخدم في سلاسل الوصول: c:idx: += 1

المسند على dynamicFieldAccessExpr يمنع الغموض مع الوصول النمطي c:next:.

التحقق من نطاق الحقول​

rangeFieldCheck
: ID COLON expr DOTDOT expr COLON cmpOp expr COLON block
;

cmpOp
: '<' | '>' | '<=' | '>=' | '==' | '!='
;

DOTDOT
: '..'
;

يتحقق التحقق من نطاق الحقول من نطاق من الحقول المرقمة ويُولِّد شروطاً مسلسلة بـ ||:

  • c:1..9: == 0: — يتحقق مما إذا كان أي من c1 إلى c9 يساوي 0
  • يدعم جميع معاملات المقارنة عبر cmpOp

تدفق التحكم​

If / Orif / Else​

ifStmt
: IF expr COLON block (ORIF expr COLON block)* (ELSE COLON block)? # ifWithBlock
;

Switch / Switchloop​

switchStmt
: SWITCH expr COLON switchBlock # switchWithBlock
| SWITCHLOOP expr COLON switchBlock # switchLoopWithBlock
;

switchBlock
: INDENT switchClause+ DEDENT
;

switchClause
: caseClause
| defaultClause
;

caseClause
: CASE? expr COLON block
;

defaultClause
: DEFAULT COLON block
;

breakStmt
: BREAK
;

continueStmt
: CONTINUE
;

While​

whileStmt
: WHILE expr COLON block
;

ثلاثي​

ternaryStmt
: expr '?' inlineStatement ':' inlineStatement
;

Try / Catch / End​

tryFailStmt
: TRY COLON block (FAIL | CATCH) COLON block (END COLON block)?
;

التعبيرات الكاملة (expr)​

expr
: literal # literalExpr
| ARROW receiver ':' ID exprListPipe # methodCallExpr
| ARROW receiver ':' ID exprList # methodCallExprArgs
| ARROW receiver ':' ID # methodCallExprNoArgs
| ID exprList # functionCallExpr
| accessChain # refOrAddrExpr
| expr '++' # postIncrementExpr
| expr '--' # postDecrementExpr
| expr op=('*' | '/' | '%') expr # mulDivExpr
| expr op=('+' | '-') expr # addSubExpr
| expr op=('<<' | '>>') expr # shiftExpr
| expr op=('<' | '>' | '<=' | '>=' | '==' | '!=' | '=#=') expr # cmpExpr
| expr op='&' expr # bitwiseAndExpr
| expr op='^' expr # bitwiseXorExpr
| expr op='|' expr # bitwiseOrExpr
| expr '&&' expr # logicalAndExpr
| expr '||' expr # logicalOrExpr
| DBL_COLON expr DBL_COLON # doubleColonExpr
| '++' expr # preIncrementExpr
| '--' expr # preDecrementExpr
| '~' expr # bitwiseNotExpr
| AT expr # addressExpr
;

الأسبقية (من الأدنى إلى الأعلى):

  1. OR منطقي ||
  2. AND منطقي &&
  3. OR بتية |
  4. XOR بتية ^
  5. AND بتية &
  6. المقارنات < > <= >= == != =#=
  7. الإزاحة << >>
  8. الجمعية + -
  9. الضربية * / %
  10. اللاحقة ++ --
  11. البادئة ++ -- ~ @
  12. تجميع بعلامتي قولون :: ::

عناصر التعبير (exprItem)​

نفس معاملات expr، مُهيكل كعناصر. يتضمن المقارنات والمعاملات المنطقية.

exprItem
: literal # literalItem
| ARROW receiver ':' ID exprListPipe # methodCallItem
| ARROW receiver ':' ID exprList # methodCallArgsItem
| ARROW receiver ':' ID # methodCallNoArgsItem
| accessChain # refOrAddrItem
| exprItem '++' # postIncrementItem
| exprItem '--' # postDecrementItem
| exprItem op=('*' | '/' | '%') exprItem # mulDivItem
| exprItem op=('+' | '-') exprItem # addSubItem
| exprItem op=('<<' | '>>') exprItem # shiftItem
| exprItem op=('<' | '>' | '<=' | '>=' | '==' | '!=' | '=#=') exprItem # cmpItem
| exprItem op='&' exprItem # bitwiseAndItem
| exprItem op='^' exprItem # bitwiseXorItem
| exprItem op='|' exprItem # bitwiseOrItem
| exprItem '&&' exprItem # logicalAndItem
| exprItem '||' exprItem # logicalOrItem
| DBL_COLON expr DBL_COLON # doubleColonItem
| '++' exprItem # preIncrementItem
| '--' exprItem # preDecrementItem
| '~' exprItem # bitwiseNotItem
| AT exprItem # addressItem
;

عناصر التعبير البسيطة (simpleExprItem)​

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

simpleExprItem
: literal # simpleLiteralItem
| ARROW receiver ':' ID exprListPipe # simpleMethodCallItem
| ARROW receiver ':' ID exprList # simpleMethodCallArgsItem
| ARROW receiver ':' ID # simpleMethodCallNoArgs
| accessChain # simpleRefOrAddrItem
| simpleExprItem '++' # simplePostIncrementItem
| simpleExprItem '--' # simplePostDecrementItem
| simpleExprItem op=('*' | '/' | '%') simpleExprItem # simpleMulDivItem
| simpleExprItem op=('+' | '-') simpleExprItem # simpleAddSubItem
| simpleExprItem op=('<<' | '>>') simpleExprItem # simpleShiftItem
| simpleExprItem op='&' simpleExprItem # simpleBitwiseAndItem
| simpleExprItem op='^' simpleExprItem # simpleBitwiseXorItem
| simpleExprItem op='|' simpleExprItem # simpleBitwiseOrItem
| DBL_COLON expr DBL_COLON # simpleDoubleColonItem
| '++' simpleExprItem # simplePreIncrementItem
| '--' simpleExprItem # simplePreDecrementItem
| '~' simpleExprItem # simpleBitwiseNotItem
| AT simpleExprItem # simpleAddressItem
;

مستبعد: cmpItem, logicalAndItem, logicalOrItem (المقارنات والمعاملات المنطقية).

سلاسل الوصول والمستقبلات​

receiver
: AT? primaryAccess (':' ID)*
;

accessChain
: primaryAccess
| accessChain ':' ID
| AT primaryAccess
;

primaryAccess
: ID # primaryAccessId
| ID COLON INTEGER COLON # dynamicFieldAccess
| ID COLON simpleExprItem COLON { self._input.LA(1) != self.ID and self._input.LA(1) != self.COLON }? # dynamicFieldAccessExpr
| ADDR accessChain # primaryAccessAddr
;

سلاسل الوصول تدعم الوصول إلى الحقول المتداخلة عبر : (مثل pkt:meta:flags). الوصول الديناميكي يأتي بنمطين:

  • c:1: — فهرس حرفي صحيح
  • c:expr: — فهرس تعبيري (يستخدم simpleExprItem، المسند يمنع الغموض مع الوصول النمطي c:next:)

استدعاءات الطرائق والدوال​

methodCallStmt
: ARROW receiver ':' ID { self._input.LA(1) != self.ASSIGN and self._input.LA(1) != self.COLON }? exprList
| ARROW receiver ':' ID { self._input.LA(1) != self.ASSIGN and self._input.LA(1) != self.COLON }?
;

functionCallStmt
: ID exprList
;

exprList
: simpleExprItem simpleExprItem*
;

exprListPipe
: PIPE INDENT expr expr* DEDENT
;

استدعاءات الطرائق تستخدم البادئة -> للتمييز عن الوصول للحقول:

  • ->b:reset — استدعاء بدون معاملات (تعليمات)
  • ->b:set move player — طريقة بمعاملات
  • win = ->b:winner — استدعاء طريقة في سياق تعبير

الرمز ARROW (->) يزيل الغموض مع الوصول الديناميكي للحقول (c:idx:).

تعليمات الطباعة​

printStmt
: PRINT printItem printItem* # printAlt
;

printItem
: expr
;

القيم​

literal
: INTEGER
| STRING
| ASSIGN
;

الكلمات المفتاحية (رموز معجمية)​

الكلمات المفتاحية مُعرّفة كرموز معجمية (وليس قواعد تحليل)، مما يضمن أولويتها على المُعرّفات:

IF : 'if' ;
ORIF : 'orif' ;
ELSE : 'else' ;
SWITCH : 'switch' ;
SWITCHLOOP : 'switchloop' ;
CASE : 'case' ;
DEFAULT : 'default' ;
BREAK : 'break' ;
CONTINUE : 'continue' ;
WHILE : 'while' ;
TRY : 'try' ;
FAIL : 'fail' ;
CATCH : 'catch' ;
END : 'end' ;
JUMP : 'jump' ;
FUNCTIONS : 'functions' ;
IN : 'in' ;
BS : 'bs' ;
PRINT : 'print' ;

القواعد المعجمية​

ADDR_EQ : '=#=' ;
ADDR_ASSIGN : '#=' ;
ADDR : '#' ;
ID : [\p{L}_][\p{L}\p{N}_]* ;
INTEGER : [0-9]+ | '0x' [0-9a-fA-F]+ | '0b' [01]+ ;
STRING : TRIPLE_DQUOTE ( '\\' . | . )*? TRIPLE_DQUOTE
| TRIPLE_SQUOTE ( '\\' . | . )*? TRIPLE_SQUOTE
| '"' (~["\\\r\n] | '\\' .)* '"'
| '\'' (~['\\\r\n] | '\\' .)* '\''
;

fragment TRIPLE_DQUOTE : '"""' ;
fragment TRIPLE_SQUOTE : SQUOTE SQUOTE SQUOTE ;
fragment SQUOTE : '\'' ;

ASSIGN : '=' ;
DOTDOT : '..' ;
DBL_COLON : '::' ;
ARROW : '->' ;
COLON : ':' ;
PIPE : '|' ;
SEMI : ';' ;
AT : '@' ;

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

NL : '\r\n' | '\n' | '\r' ;

---

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

### توزيع الرموز (Token Disambiguation)

يحل ANTLR غموض الرموز باستخدام الأولوية التالية:

1. **أطول تطابق:** قاعدة المحلل المعجمي التي تستهلك أكبر عدد من الأحرف تفوز.
2. **ترتيب القواعد:** عندما تتطابق قاعدتان بنفس الطول، تفوز القاعدة المُعرّفة أولاً في القواعد.

هذا يعني أن الكلمات المفتاحية (المُعرّفة أولاً) لها دائماً أولوية على المُعرّفات (`ID` مُعرّف بعد جميع الكلمات المفتاحية)، وأن معاملات متعددة الأحرف مثل `ADDR_EQ` (`=#=`) تُطابق قبل معاملات أحادية الحرف (`ASSIGN` `=`, `ADDR` `#`).

### قواعد تحليل السلاسل النصية

تستخدم القيم النصية المطابقة غير الجشعة (`*?`) للتعامل مع تسلسلات الهروب:

```antlr
STRING : TRIPLE_DQUOTE ( '\\' . | . )*? TRIPLE_DQUOTE

البديل '\\' . يستهلك تسلسل هروب (خط مائل عكسي + أي حرف). البديل . يستهلك حرفاً عادياً. *? (غير جشع) يضمن توقف المطابقة عند المُحدد الختامي.

الملفات المُولَّدة​

تشغيل ANTLR على Raml.g4 يُنتج أربعة ملفات:

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

يُستخدم نمط الزائر من قبل كل من المفسّر ومولّد كود المصرّف لاجتياز شجرة التحليل وإنتاج المخرجات.