REPL Reference

The Sigil REPL (Read-Eval-Print Loop) provides interactive development with module context switching, error recovery, and debugging features.

Starting the REPL

sigil repl              # Start interactive REPL
sigil repl --nrepl      # Start with network REPL server (port 7888)
sigil repl --nrepl 9999 # Start nREPL on custom port

Basic Usage

The REPL prompt shows the current module context:

sigil> (+ 1 2)
=> 3
sigil> (define greeting "hello")
sigil> greeting
=> "hello"

Multi-line input is supported — the REPL waits for balanced parentheses:

sigil> (define (factorial n)
         (if (<= n 1)
             1
             (* n (factorial (- n 1)))))
sigil> (factorial 5)
=> 120

Commands

Commands are prefixed with , (comma):

Module Context

Switch the current module to redefine its bindings:

sigil> ,m (sigil json)
sigil json> (define (my-helper x) ...)  ; Defined in (sigil json)
sigil json> ,m ()
sigil>  ; Back to default context

Import a module's exports into the current session:

sigil> ,use (sigil test)
sigil> (assert-equal 1 1)  ; Now available
=> #t

Error Handling

When an error occurs, the REPL displays it and returns to the prompt instead of crashing:

sigil> (car 5)
Error (vm-error): car: expected pair, got integer

Stack trace (most recent call first):
  0: car
     at <repl>:1:1

sigil>

Debug Mode

On error, you can inspect the stack:

sigil> (define (broken) (car 5))
sigil> (broken)
Error (vm-error): car: expected pair, got integer

Stack trace (most recent call first):
  0: car
     at <repl>:1:18
  1: broken
     at <repl>:2:1

debug[0]>

Debug mode commands:

Example session:

debug[0]> ,bt
  0: car
     at <repl>:1:18
  1: broken
     at <repl>:2:1
  [3 anonymous frames hidden]

debug[0]> ,f 1
Frame 1: broken
  at <repl>:2:1

debug[1]> ,abort
sigil>

Keyboard Shortcuts

Network REPL (nREPL)

The nREPL server enables IDE integration:

sigil repl --nrepl

Default port: 7888

The nREPL protocol uses S-expression messages for:

• Code evaluation
• Symbol completion
• Documentation lookup
• Macro expansion
• Module listing

See Editor Setup for Emacs integration.

Session Tips

Reloading Code

After editing a file, reload it:

sigil> ,load src/my-module.sgl

Or switch to the module and redefine functions interactively:

sigil> ,m (my-app utils)
my-app utils> (define (helper x) ...)  ; Redefine

Exploring Modules

List available modules:

sigil> (module-names)
=> ((sigil core) (sigil json) (sigil http) ...)

See a module's exports:

sigil> ,use (sigil core)
sigil> (exports)
=> (filter-map fold-left assoc-ref ...)

Catching Errors in Code

Use guard to handle errors:

(guard (err
        ((vm-error? err) (display "VM error caught\n"))
        (else (raise err)))
  (car 5))

VM-level errors (type errors, bounds checks, etc.) can now be caught by guard.