Grammar Specification

program         = { declaration } EOF ;

declaration     = type_def
                | type_signature
                | import_stmt
                | export_stmt
                | module_decl
                | test_block
                | extern_decl
                | trait_def
                | trait_impl
                | binding ;

type_def        = "type" TYPE_NAME { TYPE_VAR } "=" type_body ;

type_body       = constructor { "|" constructor }
                | "|" constructor { "|" constructor } ;

constructor     = CONSTRUCTOR_NAME [ constructor_args ] ;

constructor_args = "(" field_list ")"
                 | type { type } ;

field_list      = field { "," field } ;

field           = IDENT { attribute } ;

attribute       = "@" attr_name [ "(" attr_args ")" ] ;

attr_name       = IDENT { "-" IDENT } ;     (* supports hyphenated names *)

attr_args       = attr_arg { "," attr_arg } ;

attr_arg        = STRING | INT | FLOAT | "true" | "false" | IDENT ;

import_stmt     = "import" import_path [ "as" IDENT ]
                | "import" import_path "." "{" import_list "}" ;

import_path     = STRING | module_path ;

module_path     = IDENT { "." IDENT } ;

import_list     = import_item { "," import_item } ;
import_item     = IDENT [ "as" IDENT ] ;

export_stmt     = "export" ( binding | type_def ) ;

module_decl     = "module" module_path ;

test_block      = [ "@skip" [ STRING ] ] "test" [ test_name ] "=>" indented_block ;

test_name       = STRING | KEYWORD_LITERAL ;

test "basic assertions" =>
  assert!(2 + 2 == 4)
  assert-eq!(1 + 1, 2)
  assert-ne!("hello", "world")
  assert-true!(true)
  assert-false!(false)

test "option assertions" =>
  assert-some!(Some 42)
  assert-none!(None)

test "result assertions" =>
  assert-ok!(Ok 42)
  assert-err!(Err "error")

test "comparison assertions" =>
  assert-lt!(3, 5)
  assert-gt!(10, 5)
  assert-lte!(3, 3)
  assert-gte!(5, 5)

test "float approximation" =>
  assert-approx!(3.14159, 3.14, 0.01)

is_expr         = expression "is" pattern ;

as_expr         = expression "as" pattern "->" expression "else" expression ;

guard_stmt      = "guard" pattern "=" expression "else" expression ;

macro_def       = "macro" IDENT { IDENT } "=" quasiquote ;

quasiquote      = "`" "(" expression ")" ;

unquote         = "$" IDENT ;

# Define a macro
macro double x = `($x + $x)

# Usage - expands to (5 + 5) at compile time
result = double(5)  # 10

extern_decl     = extern_c_decl | extern_zig_decl ;

extern_c_decl   = "extern-c" IDENT "(" [ param_list ] ")" "->" type
                  "from" STRING "link" STRING ;

extern_zig_decl = "extern-zig" IDENT "(" [ param_list ] ")" "->" type
                  "from" STRING "link" STRING ;

param_list      = param { "," param } ;
param           = IDENT ":" type ;

trait_def       = "trait" IDENT TYPE_VAR [ "requires" constraint_list ]
                  trait_body ;

trait_body      = { trait_method } ;

trait_method    = IDENT ":" type
                | IDENT "=" expression ;

trait_impl      = "extend" type "with" IDENT [ "where" constraint_list ]
                  impl_body ;

impl_body       = { method_def } ;

method_def      = IDENT "=" expression ;

constraint_list = constraint { "," constraint } ;
constraint      = IDENT TYPE_VAR ;

type_signature  = ( IDENT | IDENT "." IDENT ) ":" type ;

binding         = { contract } pattern [ ":" type ] [ linearity ] "=" expression
                | qualified_binding ;

linearity       = " @linear"        (* must use exactly once *)
                | " @affine"        (* can use at most once *)
                | " @relevant"      (* must be used at least once *)
                | " @unrestricted"  (* no constraints - default *) ;

qualified_binding = TYPE_NAME "." IDENT "=" expression ;

contract        = "@pre" "(" expression [ "," STRING ] ")"
                | "@post" "(" expression [ "," STRING ] ")" ;

parse : Parser a -> String -> Result a ParseError
parse = fn(parser, input) => ...

Either.map-left : (a -> c) -> Either a b -> Either c b
Either.map-left = fn(f, e) => ...

# Tuple destructuring
(x, y) = (10, 20)
(a, b, c) = get-triple()

# Record destructuring with shorthand (field name becomes binding name)
{name, age} = person

# Record destructuring with explicit rename
{name: user-name, age: user-age} = person

# Partial record destructuring (extract only some fields)
{x, z} = {x: 1, y: 2, z: 3}

# Config records with optional-looking fields should use explicit defaults and
# record spread. `config.field ?? default` does not make a missing field
# optional: direct field access is still type-checked, and `??` expects an
# Option or Result value.
default-options = {enabled: true, interval: 16.0}
options = {...default-options, interval: 30.0}

# Nested destructuring
{outer: {inner}} = nested-record
((a, b), (c, d)) = nested-tuples

# Wildcards to ignore values
{keep, ignore: _} = data
(_, important, _) = triple

expression      = using_expr ;

using_expr      = "using" IDENT { "," IDENT } "=>" using_body
                | defer_expr ;

using_body      = expression
                | indented_block ;

defer_expr      = "defer" expression | null_coalesce ;

null_coalesce   = pipe_expr { "??" pipe_expr } ;

pipe_expr       = send_expr { ( "|>" | "|>>" ) send_expr } ;

send_expr       = or_expr [ "<-" or_expr ] ;

or_expr         = and_expr { ( "||" | "or" ) and_expr } ;

and_expr        = is_as_expr { ( "&&" | "and" ) is_as_expr } ;

is_as_expr      = equality [ "is" pattern ]
                | equality "as" pattern "->" expression "else" expression
                | equality ;

equality        = comparison { ( "==" | "!=" ) comparison } ;

comparison      = range_expr { ( "<" | "<=" | ">" | ">=" ) range_expr } ;

range_expr      = concat [ ( "..<" | "..=" ) concat ] ;

concat          = cons { "++" cons } ;

cons            = term { ( "::" | "@" ) term } ;

term            = factor { ( "+" | "-" ) factor } ;

factor          = unary { ( "*" | "/" | "%" ) unary } ;

unary           = ( "-" | "!" ) unary | call_expr ;

call_expr       = primary { call_suffix } ;

call_suffix     = "(" [ arg_list ] ")"           (* C-style call *)
                | "." IDENT                       (* field access *)
                | "?!"                            (* error propagation *)
                | prefix_arg ;                    (* Haskell-style *)

prefix_arg      = primary ;                       (* excluding operators *)

arg_list        = expression { "," expression } ;

auth: EntropyAuth = entropy-auth RootAuth
value = using auth =>
  Math.random

value2 = using root, auth =>
  Random.float auth

primary         = INT | FLOAT | STRING | CHAR
                | "true" | "false"
                | "no-op"                         (* unit value *)
                | KEYWORD_LITERAL                 (* :symbol *)
                | IDENT
                | field_accessor
                | lambda | if_expr | match_expr | for_expr | sql_expr
                | group_or_tuple | list_literal | set_literal
                | record_literal | interpolated_string | heredoc ;

field_accessor  = "." IDENT ;                     (* shorthand for fn(x) => x.IDENT *)

lambda          = "fn" [ "(" [ param_patterns ] ")" ] "=>" lambda_body ;

param_patterns  = param_pattern { "," param_pattern } ;

param_pattern   = [ "~" ] pattern ;          (* ~ marks lazy-accepting parameter *)

lambda_body     = expression | indented_block ;

if_expr         = "if" expression "then" if_branch "else" if_branch ;

if_branch       = expression | indented_block ;

match_expr      = "match" expression match_arms ;

match_arms      = { "|" match_arm } ;

match_arm       = or_pattern [ guard ] "->" expression
                | or_pattern [ guard ] "=>" expression ;

or_pattern      = pattern { "|" pattern } ;

guard           = "when" expression | "if" expression ;

for_expr        = "for" pattern "in" expression "=>" for_body ;

for_body        = expression | indented_block ;

sql_expr        = "sql" [ expression [ "as" type_name ] ] "{" sql_content "}" ;

sql_content     = { SQL_CHAR | "${" expression [ ":" FORMAT_SPEC ] "}" } ;

group_or_tuple  = "(" expression [ "," expression { "," expression } ] ")" ;

list_literal    = "[" [ list_elements | list_comprehension ] "]" ;

list_elements   = expression { "," expression } [ "|" expression ] ;

list_comprehension = expression "for" pattern "in" expression [ "if" expression ] ;

set_literal     = "#{" [ expression { "," expression } ] "}" ;

record_literal  = "{" [ record_fields ] "}" ;

record_fields   = record_field { "," record_field } ;

record_field    = "..." expression                (* spread *)
                | IDENT ":" expression
                | IDENT ;                         (* shorthand *)

interpolated_string = STRING_START { string_part } STRING_END ;

string_part     = STRING_CONTENT
                | "${" expression [ ":" FORMAT_SPEC ] "}" ;

heredoc         = "<<~" IDENT NEWLINE heredoc_content IDENT ;

heredoc_content = { HEREDOC_CHAR | "${" expression [ ":" FORMAT_SPEC ] "}" } ;

pattern         = "_"                             (* wildcard *)
                | INT | FLOAT | STRING
                | "true" | "false"
                | KEYWORD_LITERAL
                | IDENT                           (* binding or constructor *)
                | constructor_pattern
                | tuple_pattern | list_pattern | record_pattern ;

constructor_pattern = CONSTRUCTOR_NAME [ constructor_payload ] ;

constructor_payload = "(" pattern { "," pattern } ")"
                    | "{" record_pat_fields [ ".." ] "}"
                    | pattern { pattern } ;           (* space-separated *)

tuple_pattern   = "(" pattern "," pattern { "," pattern } ")" ;

list_pattern    = "[" [ list_pat_elements ] "]" ;

list_pat_elements = ".." pattern                  (* rest at start *)
                  | pattern { "," pattern } [ ( "|" | ".." ) pattern ] ;

record_pattern  = "{" [ record_pat_fields ] "}" ;

record_pat_fields = record_pat_field { "," record_pat_field } ;

record_pat_field = IDENT [ ":" pattern ] ;

type            = simple_type [ "->" type ]       (* single-parameter function type *)
                | "(" [ function_type_params ] ")" "->" type ;

function_type_params = function_type_param { "," function_type_param } ;
function_type_param  = type [ " @borrow" ] ;

simple_type     = "Int" | "Float" | "String" | "Bool" | "Unit"
                | TYPE_NAME [ type_args ]
                | tuple_type | record_type | refinement_type
                | "(" type ")" ;

type_args       = simple_type { simple_type } ;

tuple_type      = "(" type "," type { "," type } ")" ;

record_type     = "{" [ record_type_fields ] [ "..." ] "}" ;

record_type_fields = record_type_field { "," record_type_field } ;

record_type_field = IDENT ":" type ;

refinement_type = "{" IDENT ":" type "|" expression "}" ;

refinement_construct = TYPE_NAME "!" "(" expression ")"    (* assert *)
                     | TYPE_NAME "?" "(" expression ")"    (* Option *)
                     | TYPE_NAME "?!" "(" expression ")" ; (* Result *)

indented_block  = NEWLINE INDENT { block_item } DEDENT ;

block_item      = binding | expression ;

IDENT           = LOWER_IDENT | UPPER_IDENT ;

LOWER_IDENT     = ( LETTER_LOWER | "_" ) { LETTER | DIGIT | "_" | "-" } ;

UPPER_IDENT     = LETTER_UPPER { LETTER | DIGIT | "_" | "-" } ;

LETTER          = LETTER_LOWER | LETTER_UPPER ;
LETTER_LOWER    = "a" ... "z" ;
LETTER_UPPER    = "A" ... "Z" ;
DIGIT           = "0" ... "9" ;

INT             = DECIMAL_INT | HEX_INT | BINARY_INT | OCTAL_INT ;

DECIMAL_INT     = [ "-" ] DIGIT { DIGIT | "_" } [ INT_SUFFIX ] ;

HEX_INT         = [ "-" ] "0" ( "x" | "X" ) HEX_DIGIT { HEX_DIGIT | "_" } [ BASE_INT_SUFFIX ] ;

BINARY_INT      = [ "-" ] "0" ( "b" | "B" ) BINARY_DIGIT { BINARY_DIGIT | "_" } [ BASE_INT_SUFFIX ] ;

OCTAL_INT       = [ "-" ] "0" ( "o" | "O" ) OCTAL_DIGIT { OCTAL_DIGIT | "_" } [ BASE_INT_SUFFIX ] ;

FLOAT           = [ "-" ] DIGIT { DIGIT } "." DIGIT { DIGIT } [ FLOAT_SUFFIX ] ;

HEX_DIGIT       = DIGIT | "a" ... "f" | "A" ... "F" ;
BINARY_DIGIT    = "0" | "1" ;
OCTAL_DIGIT     = "0" ... "7" ;

INT_SUFFIX      = "L"          (* int64 *)
                | "u"          (* uint32 *)
                | "uL"         (* uint64 *)
                | "I" ;        (* bigint *)

BASE_INT_SUFFIX = "L"          (* int64 *)
                | "u"          (* uint32 *)
                | "uL" ;       (* uint64 *)

FLOAT_SUFFIX    = "F"          (* float32 *)
                | "M" ;        (* decimal *)

STRING          = '"' { STRING_CHAR | ESCAPE_SEQ } '"' ;

STRING_CHAR     = any character except '"', '\', or '${' ;

ESCAPE_SEQ      = "\" ( "n" | "r" | "t" | "\" | '"' | "$" ) ;

CHAR            = "'" ( CHAR_BODY | CHAR_ESCAPE ) "'" ;

CHAR_BODY       = one UTF-8 scalar except "'", "\", or newline ;

CHAR_ESCAPE     = "\" ( "n" | "r" | "t" | "0" | "\" | "'" | '"' )
                | "\x" HEX_DIGIT HEX_DIGIT
                | "\u" HEX_DIGIT HEX_DIGIT HEX_DIGIT HEX_DIGIT
                | "\u{" HEX_DIGIT { HEX_DIGIT } "}" ;

KEYWORD_LITERAL = ":" IDENT ;

COMMENT         = "#" { any character except newline } NEWLINE ;

DOC_COMMENT     = "##" { any character except newline } NEWLINE ;

as        defer     else      export    extend    extern-c  extern-zig
false     fn        for       from      guard     if        import
in        is        link      macro     match     module    requires
sql       test      then      trait     true      type      using    when
where     with

# Result and Option types
Ok    Err    Some    None

# Backoff strategies
NoBackoff    Constant    Linear    Exponential

# Jitter strategies
NoJitter    FullJitter    EqualJitter    ProportionalJitter

# Basic tuple destructuring
point = (10, 20)
(x, y) = point
println "x = ${x}, y = ${y}"

# Multiple values
(a, b, c) = (1, 2, 3)

# Nested tuple destructuring
((x1, y1), (x2, y2)) = ((0, 0), (10, 10))

# Ignore elements with wildcard
(first, _, third) = (1, 2, 3)

# Shorthand syntax - field name becomes variable name
person = {name: "Alice", age: 30}
{name, age} = person
println "Name: ${name}, Age: ${age}"

# Explicit rename - bind to different variable names
{name: user-name, age: user-age} = person
println "User: ${user-name}"

# Partial destructuring - only extract needed fields
config = {host: "localhost", port: 8080, debug: true}
{port} = config

# Mixed shorthand and rename
{name, age: years-old} = person

# Nested record destructuring
user = {info: {name: "Bob", email: "bob@example.com"}}
{info: {name, email}} = user

# Ignore fields with wildcard
{keep, ignore: _} = {keep: 42, ignore: 999}

# Tuple destructuring in function parameters
add-points = fn((x1, y1), (x2, y2)) =>
  (x1 + x2, y1 + y2)

# Record destructuring from function return
make-point = fn(x, y) => {x: x, y: y}
{x, y} = make-point 5 10

# In for loops
pairs = [("name", "Alice"), ("role", "admin")]
for (key, value) in pairs =>
  println "${key}: ${value}"

type Option a = Some a | None

type Result a e =
  | Ok a
  | Err e

type Point = Point(x, y)

# Single-line with attributes
type User = User(id @primary-key @auto-increment, name, email @unique)

# Multi-line with attributes
type Product = Product(
  id @primary-key,
  price @default(0.0),
  category_id @fkey(Category, id),
  tags @json("tags", omitempty)
)

add-two = fn(a, b) => a + b

# Zero-arity function (parentheses optional)
get-time = fn => now()

process = fn(items) =>
  result = items |>> map square
  result

# Lazy-accepting parameter (~ sigil)
maybe-compute = fn(~value, should-force?) =>
  if should-force? then force(value) else 0

# Linearity annotation on a parameter
consume-once = fn(resource @linear) => close resource

# Trailing lambda as the final call argument
r = twice fn(x) => x + 1

# Zero-arg trailing lambda with indented body
listen app 4000 fn =>
  println "started"

# Multi-line parenthesized lambda argument
s = twice (fn(x) =>
  doubled = x * 2
  doubled)

# Simple for loop
for x in [1, 2, 3] => print(x)

# With tuple destructuring
for (k, v) in map-entries(m) => print("${k}: ${v}")

# Multi-line body
for item in items =>
  processed = transform(item)
  save(processed)

# Simple SQL
sql { SELECT * FROM users }

# With connection
sql db { SELECT * FROM users WHERE id = ${user_id} }

# With type casting
sql db as User { SELECT * FROM users WHERE id = 1 }

html = <<~HTML
  <div>
    <h1>${title}</h1>
    <p>${content}</p>
  </div>
HTML

@pre(n >= 0, "n must be non-negative")
@post(result >= 0)
factorial = fn(n) =>
  if n <= 1 then 1 else n * factorial(n - 1)

test "addition works" =>
  assert-eq!(1 + 1, 2)

@skip "not implemented yet"
test "future feature" =>
  todo()

match value
| Some x -> x
| None -> default

match point
| Point(0, 0) -> "origin"
| Point(x, 0) -> "on x-axis"
| Point(0, y) -> "on y-axis"
| Point(x, y) -> "at (${x}, ${y})"

# Head and tail
match list
| [head | tail] -> process(head, tail)
| [] -> empty()

# Rest pattern
match args
| [first, second, ..rest] -> handle(first, second, rest)
| [..all] -> handle-all(all)

decimal = 1_000_000
hex = 0xFF
binary = 0b1010_1010
octal = 0o755
int64 = 100L
bigint = 999999999999999999I
float32 = 3.14F

data |> transform |> output       # thread-first
list |>> map double |>> filter    # thread-last

# Type declarations
type PositiveInt = {n: Int | n > 0}
type NonZero = {n: Int | n != 0}
type Percentage = {p: Float | p >= 0.0 && p <= 100.0}
type NonEmptyList a = {xs: List a | not(empty?(xs))}

# Assert construction (panics on failure)
port = ValidPort!(8080)

# Safe construction (returns Option)
port = ValidPort?(user_input)
match port
| Some p -> use-port(p)
| None -> print("Invalid port")

# Safe construction (returns Result)
port = ValidPort ?! (user_input)
match port
| Ok p -> use-port(p)
| Err msg -> print("Error: ${msg}")

# Using in function signatures
divide = fn(a: Int, b: NonZero) => a / b

# Linear: must use exactly once
use-linear = fn(value @linear) => value + 1

# Affine: can use at most once
maybe-use = fn(value @affine, should-use?) =>
  if should-use? then value + 1 else 0

# Relevant: must use at least once, and may be used more than once
use-relevant = fn(value @relevant) =>
  first = value + 1
  second = value + 2
  first + second

# Unrestricted: no usage constraint
use-unrestricted = fn(value @unrestricted) => value + value

# Borrow: parameter-only, observes without consuming caller-owned linear values
observe = fn(value @borrow) => to-string value

trait Eq a
  eq: (a, a) -> Bool
  ne = fn(a, b) => !(eq a b)

extend Int with Eq
  eq = fn(a, b) => a == b

# is: Check if value matches pattern (returns Bool)
opt = Some 42
if opt is Some _ then "has value" else "empty"

# as: Extract value with default
name = user as Some u -> u.name else "anonymous"

# guard: Bind or return early
process = fn(opt) =>
  guard Some value = opt else Err "was None"
  guard true = value > 0 else Err "not positive"
  Ok (value * 2)

# Define macros with quasiquote syntax
macro double x = `($x + $x)
macro square x = `($x * $x)
macro unless cond then-val else-val =
  `(if not($cond) then $then-val else $else-val)

# Use macros (expanded at compile time)
result = double(5)         # expands to (5 + 5)
squared = square(4)        # expands to (4 * 4)
msg = unless((x > 0), "negative", "positive")

# Closed record (default) - requires exact fields
greet-closed = fn(person: {name: String}) =>
  "Hello, " ++ person.name

greet-closed({name: "Kit"})           # OK
# greet-closed({name: "Kit", age: 1}) # Type error: extra field

# Open record (opt-in with ...) - accepts extra fields
greet-open = fn(person: {name: String, ...}) =>
  "Hello, " ++ person.name

greet-open({name: "Kit"})             # OK
greet-open({name: "Kit", age: 1})     # OK - extra field allowed

# Empty open record - accepts any record
log-record = fn(r: {...}) => println(r)

# .field is shorthand for fn(x) => x.field
users = [{name: "Alice", age: 30}, {name: "Bob", age: 25}]

# These are equivalent:
names1 = users |>> map (fn(u) => u.name)
names2 = users |>> map (.name)

# Useful in pipelines
users |>> filter (fn(u) => u.age > 21) |>> map (.name)