SICP: JavaScript, Python, and Scheme Editions

This repository contains processing scripts and sources for Structure and Interpretation of Computer Programs (SICP), adapted from the original Scheme edition (SICP) into JavaScript (SICP JS) and Python (SICPy), and also publishing the original Scheme edition on its own. See the SICP JS preface for background on the JavaScript adaptation.

Editions

SICP JS

• PDF edition
• Interactive SICP JS, backed by structured per-section JSON textbook content, e.g. json/1.1.1.json
• Comparison edition, Scheme vs. JavaScript
• Search support: the frontend's Text Search and Index Search buttons fetch json/searchData.json from this public static host (not the Source Academy backend) and filter it locally; generated by yarn json (javascript/search.ts), which runs as part of deploy-pages.yml on every push to master
• Source code archive (sicpjs.zip), the programs_js extracted from the book, one file per snippet
• Single-file Markdown export (sicpjs.md), mirroring the PDF's content selection, for reading or feeding to tools that don't handle HTML/PDF/XML

SICPy

• PDF edition
• Interactive SICPy, backed by structured per-section JSON textbook content, e.g. json_py/1.1.1.json
• Comparison edition, Scheme vs. Python
• Search support: same mechanism as SICP JS above, via json_py/searchData.json
• AI support: see SICPy chatbot knowledge base below
• Source code archive (sicpy.zip), the programs_py extracted from the book, one file per snippet
• Single-file Markdown export (sicpy.md), mirroring the PDF's content selection

Scheme (the original)

• PDF edition
• Structured per-section JSON textbook content, e.g. json_scm/1.1.1.json, including generated search data (json_scm/searchData.json) — not yet wired up to a live interactive frontend, unlike JS/Python above
• Source code archive (sicp.zip), the programs_scm extracted from the book, one file per snippet
• Single-file Markdown export (sicp.md), mirroring the PDF's content selection

No comparison edition: Scheme is the comparison anchor the other two editions are diffed against, so a Scheme-vs-Scheme comparison would be nonsensical.

Details on how to generate these versions are in the repo wiki.

Platform requirement: Generating the JSON edition and extracting the programs (yarn json, yarn programs) works on any platform with Node.js. Generating the PDF edition and running the full build require Unix/macOS; Windows users can use WSL to run the shell scripts involved.

Check out our Resources for Learners, Educators and Researchers, and read more About the SICP JS Project in Interactive SICP JS.

SICPy chatbot knowledge base

chatbot_notes_py/ is a knowledge base for retrieval-augmented-generation (RAG) Q&A bots over SICPy, published alongside the other editions at chatbot_notes_py (an index.html there lists and links every file). Unlike the editions above, it is not autogenerated by the XML build pipeline: it's AI-generated on demand — not by any pipeline in this repo — and checked into git directly, regenerated only for major revisions of the book.

For each chapter there are two files:

• sicpy_notes_chapter<N>.ex, an Elixir module (Cadet.Chatbot.SicpyNotesWithIndex.Chapter<N>) with one @summary_<section> module attribute per section/subsection. Each is an original bullet-point summary of that section, followed by a "Key terms" line drawn from the book's own back-of-book index.
• sicpy_index_terms_chapter<N>.json, a term-to-section-numbers lookup built from the same index entries, for keyword-based retrieval alongside embedding-based search.

Testing the example programs

Each edition's example programs (programs_js / programs_py / programs_scm) can be tested automatically against their expected outputs, via scripts/test.js. CI (.github/workflows/ci.yml) runs all three on every push/PR; only SICPy chapters 1–3 against CPython are a required check today (see below) — everything else runs informationally (continue-on-error), either because the interpreter itself is unproven infrastructure (native JS, Scheme) or because the content isn't finished yet (SICPy chapters 4–5, py-slang).

SICP JS

yarn test
# scoped to a folder:
yarn test -- programs_js/chapter1

By default this runs through js-slang. Set JS_SLANG=0 (yarn test:native) to instead run natively on Node, using the sicp npm package — the JS analogue of sourceacademy-sicp below: it re-exports js-slang's predeclared primitives (pair, head, tail, math_*, ...) as plain functions, generated from the js-slang repo. Unlike js-slang there's no chapter/variant gating; sicp exposes everything unconditionally.

SICPy (Python)

First, generate the programs from the XML sources:

SICP_EDITION=py npx tsx ./javascript/index.js programs_py

Then run the tests:

yarn test:py

# Or scope to one chapter/section by passing a folder, same as `yarn test`:
yarn test:py -- programs_py/chapter1
yarn test:py -- programs_py/chapter1/section1/subsection4

By default the programs are run through py-slang, the Source Academy Python interpreter, which is installed as the @sourceacademy/py-slang dependency (run yarn install first). To test against a local py-slang build instead, set the PY_SLANG environment variable to its dist/index.cjs (e.g. PY_SLANG=../py-slang/dist/index.cjs).

To run against CPython instead (useful for comparison or as a ground truth — this is what scripts/run_py.py does, and what test.js shells out to when PY_SLANG=0):

yarn test:py:cpython
# scoped to a folder, same as above:
yarn test:py:cpython -- programs_py/chapter1

The CPython path needs the sicp runtime (published as sourceacademy-sicp, maintained in the py-slang repo under python/) importable from wherever python3 runs. scripts/run_py.py looks for it in this order:

1. An installed copy — pip install sourceacademy-sicp.
2. A sibling py-slang checkout — if this repo and py-slang sit next to each other on disk (e.g. both under the same parent directory), pip install -e ../py-slang/python (or nothing at all — run_py.py also falls back to importing straight out of that checkout without an install).

If neither is available, run_py.py exits with an error naming both options rather than failing with a raw ModuleNotFoundError.

Chapters 1–3 currently pass in full against CPython. Chapter 4 (the meta-circular evaluator) has a number of known, pre-existing failures unrelated to the sicp runtime itself — mostly program fragments that reference names like parse that only exist in the Source/JS edition, or that are intentionally incomplete snippets extracted from the book.

Scheme

SICP_EDITION=scm npx tsx ./javascript/index.js programs_scm
SICP_EDITION=scm yarn test:scm
# scoped to a folder, same as above:
SICP_EDITION=scm yarn test:scm -- programs_scm/chapter1

This runs through MIT/GNU Scheme (mit-scheme on PATH; on Ubuntu, sudo apt-get install mit-scheme), the only interpreter wired up for this edition — there's no ground truth to compare against the way CPython grounds SICPy. Currently well under half the suite passes; most failures trace back to programs_scm snippets not yet having their REQUIRES (cross-snippet prerequisites, e.g. a helper defined in an earlier snippet) wired up for the Scheme edition, so a snippet ends up incomplete on its own — not to actual content bugs. This is new, previously-untested infrastructure, so treat it as informational rather than authoritative for now.

Licenses

The print version of SICP JS and the ebook version will be published in 2022 by The MIT Press under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License (CC BY-NC-SA).

The text of SICP JS and SICPy is derived from the book Structure and Interpretation of Computer Programs, Second Edition, 1996, (SICP) by Harold Abelson and Gerald Jay Sussman, and is licensed by these original authors under a Creative Commons Attribution-ShareAlike 4.0 International License (CC BY-SA). SICP JS is licensed by adapters Martin Henz and Tobias Wrigstad under CC BY-SA; SICPy is licensed by adapter Martin Henz under CC BY-SA. The Scheme edition republishes the original SICP text and programs unmodified under the same CC BY-SA license, with no additional adaptation layer. A comparison edition indicates the changes that were made to SICP for the JavaScript edition; a Scheme/Python comparison edition does the same for the Python edition. Interactive SICP JS is licensed by Martin Henz, Tobias Wrigstad, and Samuel Fang under CC BY-SA; Interactive SICPy is licensed by Martin Henz and Samuel Fang under CC BY-SA. The figures in all versions are derived from figures created by Andres Raba in 2015, and are licensed by Martin Henz and Tobias Wrigstad under CC BY-SA.

The JavaScript programs in SICP JS and the Python programs in SICPy are derived from the Scheme programs in SICP and are licensed by their respective adapters (Martin Henz and Tobias Wrigstad for JavaScript; Martin Henz for Python) under the GNU General Public License v3.0.

All JavaScript and TypeScript programs that generate the SICP JS, SICPy, and Scheme versions are licensed by the contributors under the Apache License Version 2.