Design the bilingual source notation

Design the bilingual source notation

Type: prototype Status: resolved Blocked by: 04, 05 Parent: Find the ASPL MVP specification

Question

What concrete Arabic and English keyword vocabulary, grammar, identifier policy, formatting convention, and mixed-vocabulary behavior make ASPL one Arabic-first language rather than two drifting dialects, when tested through representative source examples in real left-to-right and right-to-left editing contexts?

Answer

ASPL has one grammar and one normalized token set. Arabic is the canonical vocabulary; the English words below are exact aliases recognized everywhere. Alias lookup happens after NFC normalization and before parsing. A source file has no language mode, and mixing aliases never changes semantics or produces a warning.

Reserved vocabulary

Both spellings in each row are reserved throughout a file and cannot be identifiers. ENTRY is valid only as the required function name after FN; it is not callable from ASPL source. The exact foreign-declaration fields, library and symbol spelling, C boundary types, and supported call signatures remain for the dynamic C interoperability decision. That decision must use FOREIGN for declarations and UNSAFE at each foreign call, not introduce a general unsafe block.

Builtin callable aliases

The MVP has one predeclared callable alias pair from Choose the MVP builtin environment:

These spellings remain identifier tokens rather than lexer keywords. Name resolution maps either exact NFC spelling to the same language-owned target. Source cannot declare or shadow them, and a call requires no import or foreign declaration.

Operator aliases

Both spellings in each row are reserved throughout a file. The set ==, &&, || contains no ASPL operator.

Structural grammar

After alias normalization, the core source shape is:

program       = { function | foreign-declaration } ;
function      = FN function-name "(" [ parameters ] ")" "->" type block ;
function-name = identifier | ENTRY ;
parameters    = parameter { "," parameter } ;
parameter     = identifier ":" type ;
type          = BOOL | I64 | F64 | STRING | C_PTR | UNIT ;
block         = "{" { statement } "}" ;
terminator    = ";" | "." ;
binding       = ( LET | VAR ) identifier [ ":" type ] "=" expression terminator ;
assignment    = identifier "=" expression terminator ;
conditional   = IF expression block [ ELSE block ] ;
loop          = WHILE expression block ;
return        = RETURN [ expression ] terminator ;

Call statements and every other non-block statement end in a mandatory ASCII statement terminator. Both . and ; are valid in any source file, including mixed-vocabulary source. Canonical Arabic examples use ., and English examples use ;. Parameters and annotated locals use name: type; function results use -> type. Blocks use ASCII braces.

Assignment is a statement, not an expression. Expression precedence, from tightest to loosest, is calls and grouping; unary ! and -; *, /, %; +, -; <, <=, >, >=; matches with يطابق and تطابق precede !=; and or و; then or or أو. Binary operators associate left. Unary operators associate right. There are no symbolic equality, conjunction, or disjunction operators, increments, decrements, bitwise operators, or shifts.

Literals and comments

• Decimal literals use ASCII digits. _ may separate two digits but cannot lead, trail, double, or touch a decimal point or exponent marker.
• An integer literal has digits and separators only. A floating literal has either a fraction with digits on both sides of . or an e/E exponent with an optional sign and at least one digit. A period after an integer or exponent that is not followed by an ASCII digit is a statement terminator. Hexadecimal, octal, binary, hexadecimal floating-point, NaN, and infinity spellings are not source literals.
• Strings use double quotes. The only escapes are \\, \", \0, \n, \r, \t, and \u{...} containing one valid Unicode scalar value in one through six hexadecimal digits. Raw line breaks, invalid scalar values, and unknown escapes are errors.
• // starts a line comment. /* and */ delimit a non-nesting block comment. Comments are whitespace to the parser and retain their exact contents.

Identifiers and source text

The Unicode-source decision applies without a vocabulary exception: strict UTF-8, pinned Unicode 17.0 data, NFC identity, case-sensitive comparison, the documented XID_Start/XID_Continue profile plus _, and one Arabic or Latin strong script per identifier. A file may contain identifiers from both scripts, but one identifier may not mix them. Arabic-Indic digits, non-ASCII structural punctuation, ZWJ, ZWNJ, default-ignorables, and restricted identifier characters are rejected as already specified.

Identifiers, strings, comments, C symbols, and file paths are never translated. The formatter preserves the alias spelling at each occurrence by default. A later explicit vocabulary-conversion action may rewrite keyword aliases, foreign-adapter aliases, and a resolved builtin alias. It never rewrites an ordinary identifier that merely resembles one of those spellings. Canonical documentation examples use Arabic aliases; equivalent English fixtures are generated or checked against the same normalized-target tests.

Formatting convention

Canonical formatting uses four spaces, never tabs. It does not column-align tokens with extra spaces. A block's opening brace stays on its header line, else stays on the closing-brace line, and each statement occupies one line. Statement terminators remain visible and mandatory; the formatter does not infer or omit them. Canonical Arabic examples use periods, English examples use semicolons, and mixed source may use either spelling.

Bidirectional display contract

The file stores and the compiler parses logical token order. An editor may present lexical atoms in RTL or LTR order without rewriting that sequence. Arabic-interface examples default to RTL atoms, English-interface examples to LTR atoms, and the user may switch either view.

In a token-aware view, ASCII numeric atoms always use LTR direction and comment content uses content-sensitive direction. Every other lexical atom uses the selected atom direction. This includes keywords, identifiers, strings, operators, and neutral punctuation such as {, }, (, ), :, ,, ;, and .; in RTL mode that direction is required for correct delimiter mirroring and statement-terminator placement. A plain dir="rtl" textarea is not a conforming safe display.

LRM and RLM remain permitted only at the legal token boundaries fixed by the Unicode-source decision. Controls are never allowed to change lexical meaning. Safe diagnostics expose every control by code point and name, while raw controls in string or comment contents produce warnings.

The interactive evidence is the bilingual source notation prototype, download original file. Its paired source, per-occurrence vocabulary mixer, normalized token proof, raw bidi comparison, and token-aware display exercise this contract. The RTL punctuation regression, download original file specifically checks that braces and mandatory statement terminators inherit RTL atom direction.