Runners¶

Kiwi supports multiple execution modes via the IRunner interface. Each mode is designed for a specific workflow — from running scripts to debugging syntax to interactive development.

Execution Modes¶

Runner	Purpose	Input	Example
`ScriptRunner`	Run `.kiwi` files	File path	`kiwi script.kiwi`
`StdInRunner`	Run from piped input	`stdin`	`cat script.kiwi \| kiwi`
`REPLRunner`	Interactive shell	Keyboard	`kiwi --interactive`
`DebugRunner`	Step-debug a script (kdb)	File	`kiwi --debug script.kiwi`
`ASTPrinter`	Print AST for debugging	File	`kiwi --ast script.kiwi`
`TokenPrinter`	Print tokens for debugging	File	`kiwi --tokens script.kiwi`

How They Work¶

All runners follow the same core pipeline:

Load Standard Library (once, unless debugging)
Lex -> Parse -> Interpret
Handle errors gracefully
Pass CLI args to Interpreter.CliArgs

`ScriptRunner` – Run a File¶

Use Case: Production scripts, CLI tools, automation.

kiwi examples/hello.kiwi

Loads the standard library first
Then loads hello.kiwi
Executes top-level code and main() if defined

`StdInRunner` – Run from Pipe¶

Use Case: Shell pipelines, filters, one-liners.

echo "println 'Hello from pipe'" | kiwi
# Hello from pipe

find . -name "*.kiwi" | xargs -I {} sh -c "echo '--- {} ---'; kiwi {}"

Reads all input from stdin
No file path needed
40 MB limit (configurable)
Does not close stdin — safe in pipelines

`REPLRunner` – Interactive Mode¶

Use Case: Learning, debugging, rapid prototyping.

kiwi --interactive   # long form
kiwi -i              # short form

> println 1 + 2
3
> for i in [1, 2, 3] do \
>   println i * 2 \
> end
2
4
6
> .exit

Features¶

Multi-line input with \ continuation
Immediate execution
.exit to quit
Full access to the standard library and CLI args

`ASTPrinter` – Debug the Parser¶

Use Case: Understand how code is parsed.

kiwi --ast hello.kiwi   # long form
kiwi -a hello.kiwi      # short form

Sample Output:

Generating AST: hello.kiwi

Program:
  PrintLine:
    Literal: "Hello, World!"

`DebugRunner` – Interactive Debugger (`kdb`)¶

Use Case: Step through code, inspect variables, set breakpoints.

kiwi --debug script.kiwi   # long form
kiwi -d script.kiwi        # short form

Launches the kdb interactive debugger. Starts paused at the first statement.

kdb - Kiwi Debugger
Debugging: script.kiwi
Type 'h' for help, 's' to step, 'r' to run.

=> script.kiwi:3
     1: fn greet(name)
     2:   println "Hello, ${name}!"
  => 3:   greet("world")
(kdb)

Commands¶

Command	Alias	Description
`run`	`r`	Run to next breakpoint (or end)
`step`	`s`	Step into next statement
`next`	`n`	Step over (skip into function calls)
`finish`	`f`	Step out of current function
`b <line>`		Set breakpoint at line in current file
`b <file>:<line>`		Set breakpoint at file:line
`d <n>`		Delete breakpoint #n
`info b`		List all breakpoints
`p <expr>`		Evaluate and print an expression
`locals`	`l`	Show local variables in current scope
`backtrace`	`bt`	Show call stack
`list [line]`		Show source around current or given line
`help`	`h`	Show command help
`quit`	`q`	Exit debugger

Standard library files are automatically skipped — the debugger only pauses in user code.

`TokenPrinter` – Debug the Lexer¶

Use Case: Fix syntax errors, learn tokenization.

kiwi --tokens hello.kiwi   # long form
kiwi -t hello.kiwi         # short form

Sample Output:

Tokenizing: hello.kiwi

Token #               Type  Name                 Text                
-------               ----  ----                 ----                
1                  Keyword  KW_PrintLn           println             
2                   String  Default              Hello, World!       
3                      Eof  Default

Standard Library¶

Loaded automatically in ScriptRunner, StdInRunner, and REPLRunner
Skipped in --ast and --tokenize
Configured in kiwi-settings.json
Last file wins (for overrides)

Error Handling¶

All runners catch: - KiwiError -> Pretty print with file/line - Exception -> Full crash log + stack trace

Quick Testing¶

# Run a script
kiwi test.kiwi

# Pipe input
echo "println 100" | kiwi

# Interactive
kiwi -i

# Step debugger
kiwi -d test.kiwi

# Debug parser
kiwi -a test.kiwi

# Debug lexer
kiwi -t test.kiwi