FMPL, the language guide

git clone https://github.com/nnunley/fmpl.git && cd fmpl
just build              # bootstrap the FMPL-generated parser, then build
cargo run -p fmpl-cli   # the REPL
cargo run -p fmpl-web   # web UI on http://localhost:3000
cargo run -p fmpl-tui   # terminal UI

There’s also a full browser REPL for blank-slate scratch sessions (opens in a new tab) — but the guided path continues right here: every block below runs in place.

"Hello, World!"   -- String literals evaluate to themselves
42                -- Numbers evaluate to themselves
true              -- Booleans evaluate to themselves

-- Numbers
42
3.14
-10

-- Strings
"Hello, World!"
"Line 1\nLine 2\tTabbed"   -- Escape sequences: \n \t \r \\ \" \' \0

-- Booleans
true
false

-- Null
null

-- Single-line comments start with double dash

/*
   Multi-line comments
   are supported
*/

-- Arithmetic operators
1 + 2          -- 3
10 - 4         -- 6
3 * 4          -- 12
15 / 3         -- 5

-- Comparison operators
1 == 1         -- true
1 != 2         -- true
5 < 10         -- true
5 <= 5         -- true
10 > 5         -- true
10 >= 10       -- true

-- Logical operators
true && false  -- false
true || false  -- true
!true          -- false

Arithmetic is checked — overflow is a clean error, not a panic. Exponentiation (**) is planned but not yet implemented. String concatenation uses + and requires both operands to be strings: a mixed "n = " + 42 is a type mismatch and evaluates to null.

-- List literals (`;` separates consecutive expressions — a `[` opening a
-- new line would otherwise be read as indexing the previous expression)
[1, 2, 3];
["apple", "banana", "cherry"];
[1, "mixed", true];

-- Empty list
[]

-- Indexing, length, and (immutable) append
let numbers = [1, 2, 3]
numbers[0]       -- => 1
numbers.len()    -- => 3
numbers.push(4)  -- => [1, 2, 3, 4]  (a new list; `numbers` is unchanged)

Lists are immutable. The higher-order methods work — [1, 2, 3].map(\x x * 2) returns [2, 4, 6], and .fold() is available. For element access beyond indexing, use pattern matching with the @ operator or recursive functions.

-- Map literal
%{name: "Alice", age: 30, city: "NYC"}

-- Empty map
%{}

-- Map access
let person = %{name: "Bob", age: 25}
person.name              -- "Bob"
person.age               -- 25

-- Basic object (must be named)
object counter {
  count: 0
  increment(): self.count + 1
  value(): self.count
}

Objects must be named in the current implementation. The receiver inside methods is self — there is no this. Anonymous object literals and constructors (^name) are planned features.

-- Match strings against regex-style patterns
"hello" @ {
  [a-z]+ => "word"
}
-- Returns: "word" (matches [a-z]+)

"12345" @ {
  [0-9]+ => "number"
}
-- Returns: "number"

-- Extract values using bindings, with a wildcard fallback arm
let response = %{status: 200, body: "ok"}

response @ { %{status: _:code, body: _:msg} => msg; _ => "other" }
-- Returns: "ok"

-- Nested map patterns work too
%{outer: %{inner: "value"}} @ { %{outer: %{inner: _:i}} => i }
-- Returns: "value"

%{status: 200, body: "ok"} @ {
  %{status: _:s} when s == 200 => "success";
  %{status: _:s} => "failed"
}
-- Returns: "success"

%{code: 404} @ { %{code: _:c} when c == 404 => "not_found"; _ => "found" }
-- Returns: "not_found"

Literal values directly inside map patterns (%{status: 200} => ...) are not yet supported — the compiler rejects them. Bind and guard, as above.

-- Match a list and extract elements
[1, 2, 3] @ { [ _:x, _:y, _:z ] => [x, y, z] }
-- Returns: [1, 2, 3]

-- Length must match: this arm does not match a 3-element list
[1, 2, 3] @ { [ _:x, _:y ] => "two"; _ => "not two" }
-- Returns: "not two"

-- Empty list pattern
[] @ { [] => "empty" }
-- Returns: "empty"

Rest patterns ([first | rest]) are planned but not yet implemented. In the REPL, write @ { ... } match blocks on a single line with ; between arms — multi-line @ { blocks are routed to the grammar engine. Multi-line works fine with the match keyword form.

match 5 { n if n > 3 => "big"; _ => "small" }
-- Returns: "big"

let response = %{
  tool: "curl.get",
  args: %{url: "https://example.com"}
}

response.tool
-- Returns: "curl.get"

response.args.url
-- Returns: "https://example.com"

-- Define a grammar: capture the digits, return them from the action
let g = grammar { num = [0-9]+:d => d }

"42" @ g.num
-- Returns: "42"

-- Actions are arbitrary expressions
let shout = grammar { word = [a-z]+:w => w + "!" }
"hello" @ shout.word
-- Returns: "hello!"

-- Apply built-in base grammar rules to input
"12345" @ base::parser.integer   -- Returns: "12345"
"hello" @ base::parser.word      -- Returns: "hello"

Grammar inheritance (<: with <super.rule> overrides) is a designed feature that is deliberately deferred (DESIGN-005). Compose grammars by referencing shared rules for now.

-- if-then-else
if 15 > 10 then "big" else "small"
-- Returns: "big"

-- Nested with expressions
if 150 > 100 then
  "huge"
else if 15 > 10 then
  "big"
else
  "small"
-- Returns: "huge"

-- With let bindings
let (value = 42)
  if value > 10 then "big" else "small"
-- Returns: "big"

-- Sum numbers recursively (lambda bound at top level)
let sum_range = \start, end if start > end then 0 else start + sum_range(start + 1, end)

sum_range(1, 10)
-- Returns: 55

-- Factorial via recursion
let factorial = \n if n <= 1 then 1 else n * factorial(n - 1)

factorial(5)
-- Returns: 120

Recursion works through top-level (statement-style) let bindings — the lambda body resolves the name at call time. Scoped let (f = ...) expression bindings cannot see themselves recursively yet (a known limitation; see docs/known-gaps.md).

let numbers = [1, 2, 3, 4, 5]
let doubled = numbers.map(\x x * 2)
doubled.fold(0, \acc, x acc + x)  -- => 30

-- let-in expression (scoped binding)
let (x = 42) x * 2
-- Returns: 84

-- Multiple bindings
let (x = 10, y = 20) x + y
-- Returns: 30

-- Statement-style let (binds to current scope)
let x = 42
let y = x * 2
y + 10
-- Returns: 94

-- Bind a lambda to a name
let add = \a, b a + b
add(1, 2)           -- 3

-- The lambda keyword form is equivalent
let inc = lambda (n) n + 1
inc(41)             -- 42

The name(args): body definition syntax only exists inside object blocks (as method definitions) — it is not a top-level function form. Functions must be defined before they’re called.

-- Lambda syntax: single param, multi-param (comma-separated), curried
\x x + 1
\x, y x + y
\x \y x + y

-- Apply lambda immediately
(\x x * 2)(5)       -- 10

-- Store and call later
let doubler = \x x * 2
doubler(7)          -- 14

-- Curried application
let addc = \x \y x + y
addc(3)(4)          -- 7

-- Functions can take other functions as arguments
let apply_twice = \f, x f(f(x))
let add_one = \x x + 1

apply_twice(add_one, 5);
-- Returns: 7

-- Built-in higher-order list methods
[1, 2, 3].map(\x x * 2)
-- Returns: [2, 4, 6]

-- Define object
object counter {
  count: 0
  increment(): self.count + 1
  value(): self.count
}

-- Access methods via the object name
counter.value()       -- 0
counter.increment()   -- 1

object greeter {
  name: "world"
  show(): "Hello, " + self.name
}

greeter.show()
-- Returns: "Hello, world"

The receiver is self, as in Python or Smalltalk — there is no this, and using this silently breaks the enclosing object definition.

-- Create tagged values
[:Int, 42];
[:Binary, :+, [:Int, 1], [:Int, 2]];
[:User, "alice", %{active: true}]

-- Pattern match on tagged values (bare identifiers bind in tagged patterns)
let value = [:Binary, :+, [:Int, 1], [:Int, 2]]
value @ {
  [:Binary, :+, a, b] => "addition";
  [:Binary, :-, a, b] => "subtraction";
  [:Int, n] => "just a number"
}
-- Returns: "addition"

Operator symbols like :+, :-, :* are ordinary symbols and can appear in tagged values and patterns. The legacy constructor syntax :Int(42) is rejected with a hint: use [:Int, 42] instead.

let ast = ast::parse("1 + 2")
-- Returns: [:Binary, :+, [:Int, 1], [:Int, 2]]

let ast2 = ast::parse("if true then 1 else 2")
-- Returns: [:If, [:Bool, true], [:Int, 1], [:Int, 2]]

let code = ir::compile([:Add, [:LoadInt, 1], [:LoadInt, 2]])
code::eval(code)
-- Returns: 3

-- Parse source, transform AST to IR, compile, execute
let ast = ast::parse("1 + 2")

let ir = ast @ {
  [:Binary, :+, [:Int, a], [:Int, b]] => [:Add, [:LoadInt, a], [:LoadInt, b]];
  [:Binary, :-, [:Int, a], [:Int, b]] => [:Sub, [:LoadInt, a], [:LoadInt, b]];
  [:Binary, :*, [:Int, a], [:Int, b]] => [:Mul, [:LoadInt, a], [:LoadInt, b]];
  [:Binary, :/, [:Int, a], [:Int, b]] => [:Div, [:LoadInt, a], [:LoadInt, b]]
}

let code = ir::compile(ir)
code::eval(code)
-- Returns: 3

let data = [10, 20, 30]
let cursor = stream::observe(data)

-- Get current position
cursor::position(cursor)  -- => 0 (Int)

-- Advance cursor
let advanced = cursor::advance(cursor, 1)
cursor::current(advanced)  -- => 20

-- Rewind cursor
let rewound = cursor::rewind(advanced, 1)
cursor::current(rewound)  -- => 10

let data = [10, 20, 30]
let cursor1 = stream::observe(data)
let cursor2 = stream::observe(data)

cursor::position(cursor1)  -- => 0
cursor::position(cursor2)  -- => 0 (independent cursor)

let advanced = cursor::advance(cursor1, 1)
cursor::position(advanced)   -- => 1
cursor::position(cursor2)   -- => 0 (unchanged)

-- Parse JSON string
let json_str = "{\"name\": \"Alice\", \"age\": 30}"

-- Use json::parse builtin
let parsed = json::parse(json_str)
-- Returns: %{age: 30, name: "Alice"}

-- Validate structure
parsed @ {
  %{name: _:n, age: _:a} when a >= 18 => "Adult: " + n;
  %{name: _:n, age: _:a} => "Minor: " + n;
  _ => "Invalid structure"
}
-- Returns: "Adult: Alice"

requires network — not run by CI

-- Make HTTP GET request using the curl builtin
let response = curl.get("https://api.example.com/data")

-- Parse JSON response
let data = json::parse(response)

-- Extract specific fields
data @ {
  %{status: _:s, results: _:r} when s == "ok" => r;
  %{error: _:e} => "Error: " + e;
  _ => "Unknown response"
}

requires network — not run by CI

-- Dispatch tool calls by binding the tool name and guarding on it
let handle_tool_call = \tc tc @ {
  %{tool: _:t, args: _:a} when t == "curl.get" => curl.get(a.url);
  %{tool: _:t, args: _:a} when t == "curl.post" => curl.post(a.url, a.body);
  %{text: _:txt} => txt;
  _ => "Error: Unrecognized response"
}

-- Simulate LLM response
let llm_output = "{\"tool\": \"curl.get\", \"args\": {\"url\": \"https://example.com\"}}"
let parsed = json::parse(llm_output)

-- Handle the tool call (performs the HTTP request)
handle_tool_call(parsed)

design sketch  not yet runnable

let agent_turn = \input, history
  llm_complete(%{history: history, input: input}) @ {
    %{tool: _:t, args: _:a} => agent_turn(execute_tool(t, a), history);
    %{answer: _:ans} => ans;
    _ => "Error: Unexpected LLM output"
  }

let result = agent_turn("Search for latest Rust version", [])

design sketch  not yet runnable

grammar ToolAgent <: base::tree {
  -- Main loop: process messages
  turn = message:m => {
    let ctx = %{history: get_history()}
    ::llm_complete(m, ctx) |> tool_output
  }

  -- Handle LLM output stream
  tool_output =
    | %{tool: t, args: a} => {
        let result = ::execute_tool(t, a)
        turn(result)  -- recurse with result
      }
    | %{done: r} => r  -- terminate
    | %{text: t} => t  -- stream text
}