Files
marqdo-cli/spec/expression.ebnf
T
cflmy 49835424ee docs(spec): adopt RFC-LANG-0002 unified language semantics
Replace the Strong/Emph/List/Quote mapping in place with the single
@exec/@knowledge heading-mode model, unified payload carriers and keyword
control flow.

- add the authoritative RFC, ADR-0052 and a historical ADR index
- rewrite spec/mapping.md and spec/expression.ebnf as the normative
  mapping/statement grammar; update evaluation, references, math,
  foreign, package-format, plugin-abi, security and schema notes
- rewrite README, AGENTS, COMPATIBILITY and CHANGELOG for the breaking
  language change; update the architecture index/overview and active docs
- mark superseded planning docs, compute RFCs, evidence and syntax-role
  ADRs as historical/superseded without rewriting their decisions
- add migration guide, per-file inventory and dev-only audit scripts

The frontend/stdlib migration is completed in the following commits; this
commit contains documentation only.
2026-11-21 12:24:19 +08:00

143 lines
6.6 KiB
EBNF

(* Marqdo Statement and Expression Grammar
Status: current language contract, breaking rewrite (RFC-LANG-0002).
This replaces the earlier v1 expression-only grammar in place.
There is one grammar for every executable payload. Markdown AST decides
which closed carrier (Strong / Emph / inline Code) is a payload and where
it lives; this grammar decides what that payload means. No second parser
and no per-file syntax selector exists.
Implementation state: the Rust expression parser still implements the
previous, control-free grammar; this file is the target contract. See
docs/STATUS.md.
*)
(* One payload is exactly one statement and must consume the whole payload. *)
payload = statement , EOF ;
statement = if_stmt
| else_stmt
| while_stmt
| end_stmt
| return_stmt
| params_stmt
| assignment
| expression ;
if_stmt = "if" , space_required , expression ;
else_stmt = "else" ;
while_stmt = "while" , space_required , expression ;
end_stmt = "end" ;
return_stmt = "return" , space_required , expression ;
params_stmt = "params" , "(" , [ parameter_list ] , ")" ;
(* `if`, `else`, `while`, `end`, `return` and `params` are reserved statement
words only when they are the complete first token of a payload.
`ifdef(x)` and `returning(x)` are ordinary identifiers; a bare `if` used as
an identifier is a reserved-word error. `else`/`end` take no additional
tokens: `else x` and `end if` are syntax errors. No trailing colon:
`if x > 0:` is a syntax error. No `elif`, `for`, `break`, `continue`,
`try`, empty `return`, `end if`, or semicolon-separated multi-statement
payload exists in this revision.
Control pairing is not part of this grammar; it is a separate compile-time
stack in the frontend:
- every `if` has exactly one closing `end`;
- `else` is optional and at most one per `if`;
- every `while` has exactly one closing `end`;
- `else` must bind the top-of-stack `if`; `end` closes the top frame;
- a frame must close inside the same heading's direct body.
*)
(* Function parameter declaration. It is legal only as the first direct
execution payload of an Exec H2 function, at most once, and never inside a
list or block quote. The declaration is compile-time metadata, not a
runtime call. *)
parameter_list = parameter , { "," , parameter } , [ "," ] ;
parameter = identifier , ":" , type_name , [ "=" , expression ] ;
type_name = identifier ;
(* Parameter names are unique; positional parameters precede defaulted ones.
Types and default expressions reuse the existing signature rules. *)
(* Assignment and place writes are unchanged from the previous revision. *)
assignment = assign_target , "=" , expression ;
assign_target = identifier
| postfix_expr , "[" , expression , "]" ;
(* The index target writes one byte into an addressable Memory region; other
base values are rejected at run time. Member assignment (`a.b = 1`) and
chained assignment are parse errors. See ADR-0022. *)
expression = or_expr ;
or_expr = and_expr , { "or" , and_expr } ;
and_expr = compare_expr , { "and" , compare_expr } ;
compare_expr = add_expr , [ compare_op , add_expr ] ;
(* non-associative: "a < b < c" is a parse error; write
"a < b and b < c" instead. *)
compare_op = "==" | "!=" | "<" | "<=" | ">" | ">=" ;
add_expr = mul_expr , { ( "+" | "-" ) , mul_expr } ;
mul_expr = unary_expr , { ( "*" | "/" | "//" | "%" ) , unary_expr } ;
unary_expr = ( "not" | "-" | "+" ) , unary_expr | power_expr ;
power_expr = postfix_expr , [ "**" , unary_expr ] ;
(* right associative: 2 ** 3 ** 2 == 2 ** (3 ** 2);
-x ** 2 == -(x ** 2); 2 ** -1 is valid *)
postfix_expr = primary , { call_suffix | member_suffix | index_suffix } ;
call_suffix = "(" , [ argument_list ] , ")" ;
argument_list = argument , { "," , argument } , [ "," ] ;
argument = [ identifier , "=" ] , expression ;
(* positional arguments must all precede named arguments;
duplicate argument names are errors *)
member_suffix = "." , identifier ;
index_suffix = "[" , expression , "]" ;
primary = int_literal
| float_literal
| text_literal
| "true" | "false" | "None"
| identifier
| "(" , expression , ")"
| list_literal
| record_literal ;
list_literal = "[" , [ expression , { "," , expression } , [ "," ] ] , "]" ;
record_literal = "{" , [ record_entry , { "," , record_entry } , [ "," ] ] , "}" ;
record_entry = ( identifier | text_literal ) , ":" , expression ;
(* Lexical rules *)
identifier = xid_start , { xid_continue } ;
(* Unicode XID per UAX #31: Chinese, Latin, etc. are valid.
Reserved words cannot be identifiers:
true, false, None, and, or, not,
if, else, while, end, return, params. *)
int_literal = digit , { digit } ;
(* arbitrary precision decimal integer; no sign here (unary
minus handles negatives); no separators; no hex/octal. *)
float_literal = digit , { digit } , "." , digit , { digit } ,
[ ( "e" | "E" ) , [ "+" | "-" ] , digit , { digit } ] ;
(* requires digits on both sides of the dot; ".5" and "1."
are invalid. Floats are IEEE-754 binary64. *)
text_literal = '"' , { text_char | escape } , '"' ;
escape = "\\" , ( '"' | "\\" | "n" | "t" | "r" | "u{" , hexdigit , { hexdigit } , "}" ) ;
text_char = ? any Unicode scalar value except '"' and "\\" ? ;
(* Whitespace: any Unicode whitespace separates tokens. Newlines inside a
code-span payload are whitespace. There are no comments. `space_required`
means at least one whitespace character after the keyword. *)
(* Notes on the Markdown boundary *)
(* - A "**" inside a payload is the power operator only when it survived
Markdown parsing inside a code span or text that is not emphasis.
Authors should put multiplication/power expressions in code spans when
Markdown emphasis would otherwise consume the asterisks. *)
(* - Payload spans returned by the parser are relative to the concatenated
payload; the frontend maps them back through the text/code segments to
file spans. *)
(* - Maximum nesting depth is 128; exceeding it is an expr.parse error. *)
(* - Every payload must be fully consumed. A trailing token is a syntax error,
never an ignored suffix. *)