grammar.ebnf

/*
 * Soplang Formal Grammar Specification in Extended Backus-Naur Form (EBNF)
 *
 * Syntax conventions:
 * - | denotes alternatives
 * - [ ] denotes optional elements
 * - { } denotes repetition (zero or more)
 * - ( ) denotes grouping
 * - " " denotes literals/terminals
 * - 'a'..'z' denotes character ranges
 */

// ===== PROGRAM STRUCTURE =====
Program ::= Statement {Statement}

// ===== STATEMENTS =====
Statement ::= VariableDeclaration
            | FunctionDeclaration
            | FunctionCall
            | IfStatement
            | SwitchStatement
            | LoopStatement
            | WhileStatement
            | BreakStatement
            | ContinueStatement
            | ReturnStatement
            | AssignmentStatement
            | Block

Block ::= "{" {Statement} "}"

// ===== VARIABLE DECLARATIONS =====
VariableDeclaration ::= DynamicDeclaration | StaticDeclaration | ConstantDeclaration

DynamicDeclaration ::= "door" Identifier "=" Expression

StaticDeclaration ::= StaticType Identifier "=" Expression

ConstantDeclaration ::= "madoor" [StaticType] Identifier "=" Expression

StaticType ::= "abn"      // Integer
             | "jajab"     // Decimal
             | "qoraal"    // String
             | "bool"      // Boolean
             | "teed"      // List/Array
             | "walax"     // Object

// ===== FUNCTION DECLARATIONS =====
FunctionDeclaration ::= "hawl" Identifier "(" [ParameterList] ")" Block

ParameterList ::= Identifier {"," Identifier}

// ===== FUNCTION CALLS =====
FunctionCall ::= (Identifier | BuiltInFunction) "(" [ArgumentList] ")"
               | MethodCall

MethodCall ::= ObjectProperty "(" [ArgumentList] ")"

ArgumentList ::= Expression {"," Expression}

// ===== CONTROL FLOW =====
IfStatement ::= "haddii" "(" Expression ")" Block
               {ElseIfClause}
               [ElseClause]

ElseIfClause ::= "haddii_kale" "(" Expression ")" Block

ElseClause ::= "ugudambeyn" Block

// ===== SWITCH STATEMENT =====
SwitchStatement ::= "dooro" "(" Expression ")" "{" {CaseClause} [DefaultClause] "}"

CaseClause ::= "xaalad" Expression Block

DefaultClause ::= "ugudambeyn" Block

// ===== LOOPS =====
LoopStatement ::= "kuceli" "(" Identifier Expression "ilaa" Expression ["::" Expression] ")" Block

WhileStatement ::= "intay" "(" Expression ")" Block

BreakStatement ::= "jooji"

ContinueStatement ::= "soco"

// ===== RETURN STATEMENT =====
ReturnStatement ::= "celi" [Expression]

// ===== OBJECT ORIENTED =====
ObjectProperty ::= Expression "." Identifier

IndexAccess ::= Expression "[" Expression "]"

// ===== ASSIGNMENT =====
AssignmentStatement ::= (Identifier | ObjectProperty | IndexAccess) "=" Expression

// ===== EXPRESSIONS =====
Expression ::= LogicalExpression

LogicalExpression ::= ComparisonExpression {LogicalOperator ComparisonExpression}

ComparisonExpression ::= ArithmeticExpression {ComparisonOperator ArithmeticExpression}

ArithmeticExpression ::= Term {AdditiveOperator Term}

Term ::= Factor {MultiplicativeOperator Factor}

Factor ::= NumberLiteral
        | StringLiteral
        | BooleanLiteral
        | NullLiteral
        | Identifier
        | FunctionCall
        | ObjectProperty
        | IndexAccess
        | ListLiteral
        | ObjectLiteral
        | "(" Expression ")"
        | UnaryOperator Factor

// ===== OPERATORS =====
LogicalOperator ::= "&&" | "||"

ComparisonOperator ::= "==" | "!=" | ">" | "<" | ">=" | "<="

AdditiveOperator ::= "+" | "-"

MultiplicativeOperator ::= "*" | "/" | "%"

UnaryOperator ::= "!" | "-"

// ===== LITERALS =====
NumberLiteral ::= Digit {Digit} ["." Digit {Digit}]

StringLiteral ::= '"' {Character} '"' | "'" {Character} "'"

BooleanLiteral ::= "true" | "false" | "run" | "been"

NullLiteral ::= "null" | "maran"

ListLiteral ::= "[" [Expression {"," Expression}] "]"

ObjectLiteral ::= "{" [PropertyAssignment {"," PropertyAssignment}] "}"

PropertyAssignment ::= (Identifier | StringLiteral) ":" Expression

// ===== BASIC ELEMENTS =====
Identifier ::= (Letter | "_") {Letter | Digit | "_"}

Letter ::= 'a'..'z' | 'A'..'Z'

Digit ::= '0'..'9'

Character ::= Letter | Digit | Symbol | Whitespace

Symbol ::= '!' | '@' | '#' | '$' | '%' | '^' | '&' | '*' | '(' | ')' | '-' | '+' | '=' | '{' | '}' | '[' | ']' | ':' | ';' | '"' | "'" | '<' | '>' | ',' | '.' | '?' | '/' | '\\' | '|' | '`' | '~'

Whitespace ::= ' ' | '\t' | '\n' | '\r'

// ===== COMMENTS =====
Comment ::= SingleLineComment | MultiLineComment

SingleLineComment ::= "//" {Character} '\n'

MultiLineComment ::= "/*" {Character} "*/"

// ===== ERROR FORMATTING =====
ErrorMessage ::= "Khalad" ErrorType ":" ErrorDetail ["ee" "sadar" LineNumber "," "goobta" Position]

ErrorType ::= "lexer" | "parser" | "runtime" | "type" | "import"

ErrorDetail ::= {Character}

LineNumber ::= Digit {Digit}

Position ::= Digit {Digit}

// ===== LIST METHODS =====
ListMethod ::= "kudar"       // push
             | "kasaar"      // pop
             | "dherer"      // length
             | "kudar"       // concat
             | "leeyahay"    // contains
             | "nuqul"       // copy
             | "nadiifi"     // clear
             | "rog"         // reverse
             | "habee"       // sort
             | "jar"         // slice
             | "aaddin"      // map/transform
             | "shaandhee"   // filter
             | "muuji"      // find index

// ===== OBJECT METHODS =====
ObjectMethod ::= "fure"      // keys
               | "qiime"     // values
               | "lamaane"   // entries
               | "leeyahay"  // has
               | "tir"    // remove
               | "kudar"     // merge
               | "nuqul"     // copy
               | "nadiifi"   // clear

// ===== STRING METHODS =====
StringMethod ::= "qeybi"     // split
              | "leeyahay"   // contains
              | "dhamaad"    // endsWith
              | "bilow"      // startsWith
              | "beddel"     // replace
              | "kudar"      // join
              | "jar"        // slice

// ===== BUILT-IN FUNCTIONS =====
BuiltInFunction ::= "qor"  // print
                  | "gelin"    // input
                  | "nooc"     // typeof
                  | "abn"     // to integer
                  | "jajab"    // to float
                  | "qoraal"   // to string
                  | "bool"     // to boolean
                  | "teed"     // create list
                  | "walax"    // create object
                  | "daji"     // math.floor
                  | "kor"      // math.ceil
                  | "dherer"   // length
                  | "xul"   // random