Gerbil Koans

An Emacs-first learning environment for Gerbil Scheme.

Each lesson contains blanks named __. Replace a blank with the Gerbil expression or value that makes the check pass, then rerun the lesson from inside Emacs. The dashboard tracks progress, opens teaching guides beside the source, reveals staged hints, and can ask gerbil-mcp for symbol and failure help when it is installed.

Requirements

• Emacs 27.1 or newer
• Gerbil Scheme with gxi on PATH
• Optional: gerbil-mode for editing .ss buffers
• Optional: gerbil-mcp for symbol lookup, cookbook search, and failure help

The koans run Gerbil directly through gxi. This checkout was developed against the Gerbil installed at /opt/gerbil.

Start In Emacs

Add the package to your Emacs configuration:

(add-to-list 'load-path "/Users/user/mine/gerbil-koans/emacs")
(require 'gerbil-koans)
(setq gerbil-koans-root "/Users/user/mine/gerbil-koans")

Then open the dashboard:

M-x gerbil-koans

The dashboard is the main interface. It shows every lesson, completion state, difficulty, tags, and a short summary. Press RET on a lesson to open its source. By default, the lesson's guide opens in a side window.

Dashboard Keys

Key	Action
RET	Open the selected lesson from the dashboard
i	Read the selected lesson's conceptual guide
r	Review lessons with repeated misses
g	Refresh the dashboard

Lesson Keys

These bindings are active in lesson source buffers after opening a lesson from the dashboard.

Key	Action
C-c C-c	Run the current lesson with gxi
C-c C-n	Jump to the next __ blank
C-c C-h	Reveal the next staged hint
C-c C-i	Open the current lesson's conceptual guide
C-c C-d	Describe the Gerbil symbol at point with gerbil-mcp
C-c C-k	Find verified Gerbil cookbook patterns with gerbil-mcp
C-c C-e	Explain the last failure
C-c C-r	Open a repository reference for the lesson
C-c C-p	Open the saved progress data

Learning Loop

1. Run M-x gerbil-koans.
2. Open the first TODO lesson with RET.
3. Read the guide in the side window.
4. Jump to a blank with C-c C-n.
5. Predict the value Gerbil will produce.
6. Replace one __, then run C-c C-c.
7. If the result is wrong, read the prediction review or press C-c C-h for the next staged hint.
8. Repeat until the dashboard marks the lesson PASS.

Completion state is stored under gerbil-koans-data-directory, which defaults outside this repository in your Emacs data directory.

Optional Gerbil Coach

The Emacs interface can call gerbil-mcp when available:

• C-c C-d describes the Gerbil symbol at point.
• C-c C-k searches verified Gerbil cookbook patterns.
• C-c C-e explains the last compiler/runtime failure. For ordinary koan prediction misses, it uses the local lesson guide instead of calling MCP.

Customize gerbil-koans-mcp-command if gerbil-mcp is not on PATH.

Terminal Smoke Check

The terminal runner is mainly for quick checks and non-Emacs validation. Run one lesson from the repository root:

./bin/gerbil-koan lessons/01-first-steps.ss

Run the full smoke check:

make check

make check expects unsolved lessons to fail at blanks. It reports an error only when a lesson fails before reaching the koan checks, such as a Gerbil syntax or import problem.

Curriculum

1. 01-first-steps.ss - expressions, def, keyword arguments, rest arguments, def*
2. 02-reader-syntax.ss - brackets, quote, quasiquote, keywords
3. 03-lists-hashes-strings.ss - lists, strings, hash literals, mutable updates
4. 04-pattern-matching.ss - match, list patterns, predicates, tagged code-shaped data
5. 05-structs.ss - defstruct, predicates, accessors, mutation, destructuring
6. 06-iteration.ss - :std/iter, for/collect, for/fold, hash iteration
7. 07-errors.ss - with-catch, try, error, cleanup with finally
8. 08-modules.ss - imports, :std/format, selective imports, local definitions

Design

The lessons are ordinary Gerbil programs. support.ss defines the blank value and small reporting helpers, so an incomplete lesson reaches the relevant check instead of failing during expansion. The koans intentionally teach Gerbil forms and standard modules as Gerbil uses them.