# 2025-01-31

# pan grammar

# https://github.com/ziglang/zig-spec/blob/master/grammar/grammar.peg



########################################
# module ###############################
########################################

<program> =| <declaration>* ;

<declaration> =
| [ "pub" ] "var" [ "mut" ]  <identifier> [ <compile_type> ] "=" <expr>         ";"
| [ "pub" ] "var" "#"        <identifier> [ <compile_type> ] "=" <compile_expr> ";"
# TODO compile_var mutability..
# TODO "ref", "err", "out"
;

<compile_expr> =
| <literal>
| "#" <atom>
;

<compile_type> =
| ":" <type>
| ":" "#" <atom>
;

<assignment> =| <left_hand_side> "=" <expr> ";" ;

# TODO should the semicolon be in the statement rule ?
<statement> =
| <declaration>
| <assignment>
| <expr> ";"
| <defer_identifier> [ "|" <identifier> "|" ] <block> ";"
| <loop_control_identifier> [ <label> ] [ <expr> ] ";"
;

# keyword "defer" and "errdefer"
<defer_identifier> =| <identifier> ;

# keyword "break" and "continue"
<loop_control_identifier> =| <identifier> ;



########################################
# types ################################
########################################

<type> =
| <simple_type>
| "*" <expr>
| "[" <expr> "]" <expr>
| "[" "]" <expr>
| "?" <expr>
| <errorset> "!" <expr>
# TODO record
# TODO class
# TODO enum
# TODO union
# TODO variant
;

<simple_type> =
| "void"
| "bool"
| "u" <digit>+ # "u1", "u8", "u16", "u32", "u64"
| "i" <digit>+ # "i1", "i8", "i16", "i32", "i64"
| "usize"
| "isize"
| "f32"
| "f64"
;



########################################
# functions ############################
########################################

<function> =| <fn_lambda> [ "|" <parameter_list> "|" ] <block> ;

<fn_lambda> =
| "fn" <compile_type>  # fn, stand-alone types
| "."                  # lambda, type signature inferred
# TODO '.' prefix is large gramatic allocation
;

<parameter_list> =| ( <parameter> "," )* [ <parameter> [ "," ] ] ;

<parameter> =| [ "ref" ] [ "#" ] <identifier> [ <comp_type> ] ;



########################################
# control flow #########################
########################################

<block> =| "{" <statement>* [ <expr> ] "}" ;

<if> =| "if" "(" <expr> ")" [ "|" <parameter> "|" ] <block> [ "elif" <block> ]* [ "else" <block> ] ;

<for> =| "for" "(" <for_list> ")" [ "|" <parameter_list> "|" ] <block> [ "else" <block> ] ;

<for_list> =| ( <for_arg> "," )* <for_arg> [ "," ] ;

<for_arg> =
| <expr>
| <range>
;

<range> =| <expr> ".." <expr> ; # TODO optional <expr>s ?

# TODO update expression, after parameter, before block
<while> =| "while" "(" <expr> ")" [ "|" <parameter> "|" ] <block> [ "else" <block> ] ;

# TODO
<switch> = TODO ;



########################################
# expr #################################
########################################

<expr> =
| <binary>
# <atom> # thru the <binary_expr>s
;

# equality, comparison, addition, multiplication, unary
<binary> =| <comparison> ;

<bool_combo> =| <comparison> ( <bool_operator> <comparison> )* ;

<bool_operator> =
| "and"
| "or"
;

<comparison> =| <addition> ( <comparison_operator> <addition> )* ;
<comparison_operator> =
| "==" 
| "<>" 
| "<"  
| "<=" 
| ">"  
| ">=" 
;
<addition> =
| <multiplication> ( <addition_operator> <multiplication> )*
; # sum
<addition_operator> =
| "+"
| "-"
;
<multiplication> =| <atom> ; # product
<multiplication_operator> =
| "*"
| "/"
| "%"
;

<bitwise> = # TODO
| <expr> ( ( "`|`" | "`&`"  | "<<" | ">>" ) <expr> )*
# TODO maybe `$&` and `$|`
# TODO sign extend shift right..
# TODO rotate left, rotate right..
;

<atom> =
| <left_hand_side>
| <atom> "." "!" # `atom catch |e| { return e; }`
| <atom> "." "?" # TODO `trap` or error ? fallible function,
# `if( atom ) |a| { a } else { return error.nil; }` # fallible function
# `if( atom ) |a| { a } else { trap; }` # XXX hidden trap, like assert..
| <atom> "." "&"
| <atom> "." "~"
| <atom> "." "+"
| <atom> "." "-"
| <literal>
| <type>
| <call>
| <slice>
| <block>
| <expr> "ifnil" [ "|" <parameter> "|" ] <block>
| <expr> "iferr" [ "|" <parameter> "|" ] <block>
| <expr> "catch" [ "|" <parameter> "|" ] <switch_block> # TODO
| <if>
| <for>
| <while>
| <switch> # TODO
;

<call> =| <expr> "(" <argument_list> ")" ;

<index> =| <expr> "[" <expr> "]" ;

<slice> =| <expr> "[" [ <expr> ] ".." [ <expr> ] "]" ;

<argument_list> =| ( <expr> "," )* [ <expr> [ "," ] ] ;



########################################
# identifier and literals ##############
########################################

<identifier> =| <letter> <alphanumeric>* ;

<letter> =
| "a".."z"
| "A".."Z"
| "_"
;
<alphanumeric> =
| <letter>
| "0".."9"
;

<literal> =
| "undefined"
| "nil"
| <boolean>
| <number>
| <string>
| <function>
| <struct_literal> # TODO
;

<boolean> =
| "true"
| "false"
;

<number> =
| <integer>
| <float>
;

<integer> =
| [ <sign> ] <digit>+
| [ <sign> ] "0x" <hex>+
| [ <sign> ] "0b" <bin>+
;

<sign> =
| "+"
| "-"
;

<digit> =| "0".."9" ;
<digit_> =
| <digit>
| "_"
;
<hex> =
| <digit_>
| "a".."f"
| "A".."F"
;
<bin> =
| "0".."1"
| "_"
;

<float> =
| [ <sign> ] <digit> <digit_>* "."  <digit_>+ [ "p" [ <sign> ]  <digit_>+ ]
| [ <sign> ] "0x"       <hex>+ "."     <hex>+ [ "p" [ <sign> ]     <hex>+ ]
| [ <sign> ] "0b"       <bin>+ "."     <bin>+ [ "p" [ <sign> ]     <bin>+ ]
;

<string> =
| '"' <not_quote_not_newline>* '"'
| "/" '"' <not_newline>* "\n"
;

<not_quote_not_newline> = TODO ;

<not_newline> = TODO ;

<left_hand_side> = # resident, assignable
| <identifier>
| <atom> "." <identifier>
| <atom> "." <digit>+
| <atom> "." "*"
| <atom> "[" <expr> "]"
;



########################################
# unused.. #############################
########################################

<char> =
| <letter>
| <digit>
| <special_characters>
;

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