This document describes the interactive Read–Eval–Print Loop (REPL) for the Fun programming language: how to build/launch it, how input and execution work, line editing and completion, the REPL buffer workflow, commands, debugging helpers, and tips.
The REPL is optional at build time. It provides a fast feedback loop for experimenting with Fun code, inspecting VM state, and debugging scripts interactively.
Environment variable FUN_LIB_DIR can be used to point the REPL to the standard library directory for symbol completion and library loading. If not set, a compile-time DEFAULT_LIB_DIR (if provided) or "lib" is used.
Inside REPL-on-error, you can inspect frames, locals, disassembly, set breakpoints, and continue or step. Use :help to see available commands.
## Prompts and input model
- Primary prompt: `fun> ` when the input buffer is empty.
- Continuation prompt:
-`... ` when text exists but no extra indentation is required.
-`...N> ` (e.g., `...1> `, `...2> `) when the REPL detects open blocks needing additional indentation (2 spaces per level). This helps write multi-line constructs.
- Execution trigger: submit an empty line (press Enter on a blank line). The REPL parses the current buffer and executes it if complete; otherwise it will tell you the input looks incomplete and keep the buffer.
- When typing a :load command, Tab completes filesystem paths, including directories. A trailing slash is handled as expected. Completion attempts to compute common suffixes across candidates.
- For general input, Tab attempts to complete identifiers from the standard library symbols scanned from FUN_LIB_DIR (or DEFAULT_LIB_DIR/lib). If there are multiple matches, a menu of candidates is printed; otherwise the identifier is completed in place.
If Tab is pressed in the middle of the line (not at end), the REPL beeps instead of completing.
Enter paste mode to insert multiple lines verbatim. Finish with a single dot line: `.`. If the optional argument `run` (or `exec`) is given, the REPL will run the pasted buffer immediately.
- :mdump | :md WHAT [offset [len]] [raw] [to <file>]<br>
Dump a VM memory region. WHAT is one of: code, stack, globals and consts. Offset and length are optional; if omitted, a sensible default (up to 256 bytes) is used. With `raw`, write binary bytes. With `to <file>`, write output to a file; otherwise print to stdout as a formatted hexdump.
Run until the current frame returns (REPL-on-error/debug mode).
If an unknown command is entered, the REPL prints a hint to use :help.
## Output handling
Program output produced by VM execution is collected and then printed after each run. After printing, the VM’s output buffer is cleared.
## Errors and diagnostics
- Parse errors are reported with file:line and a caret pointing to the column. When tracing is enabled during normal execution, the VM annotates output with file/line and function names to aid debugging.
- In FUN_DEBUG builds, parse errors are also appended as comments to the history file to assist in later review.
## Environment and library path
- FUN_LIB_DIR: Overrides the standard library search path and the directory scanned for identifier completion.
- DEFAULT_LIB_DIR: Compile-time fallback path used when FUN_LIB_DIR is not set. If neither is available, the REPL defaults to the relative path "lib".
## Tips
- Use :paste run to quickly paste and execute multi-line code from the clipboard.
- :profile is handy to compare parser vs. VM time and to observe instruction counts for larger snippets.
- Combine --repl-on-error with --trace when running scripts to drop into an interactive diagnostic session at the point of failure.
- Use :mdump code/consts/stack/globals to inspect raw VM data, and :disasm to view bytecode in a human-readable form.
- [https://git.xw3.org/fun/fun/src/branch/main/examples/error/repl_on_error.fun](https://git.xw3.org/fun/fun/src/branch/main/examples/error/repl_on_error.fun){:class="git"} — example showing the REPL-on-error workflow.
