Get started

Requirements

• Python 3.10 or newer. Tested on 3.10, 3.12, and 3.14 across Linux, macOS, and Windows.
• Git. To clone the repository.
• No other dependencies. Capa is hand-written in pure Python and has zero runtime dependencies outside the standard library.

Install

Clone and install in editable mode:

$ git clone https://github.com/nelsonduarte/capa
$ cd capa
$ pip install -e .

That's it. You can verify the install by running the test suite (536 tests, takes ~15 seconds):

$ python -m unittest discover tests
............................................................
----------------------------------------------------------------------
Ran 536 tests in 14.2s

OK

Your first program

Create a file hello.capa with the following contents:

// hello.capa
fun main(stdio: Stdio)
    stdio.println("Hello, Capa!")

Run it:

$ python -m capa --run hello.capa
Hello, Capa!

The stdio: Stdio parameter is the language asking explicitly for the right to write to standard output. The runtime hands one to main, and main can hand it further down, or not. This is the whole language in one line.

The CLI

The compiler exposes five modes, one per stage of the pipeline. Each subsumes the previous: --run implies --transpile, which implies --check, and so on.

Common invocations:

$ python -m capa --check examples/io.capa
OK

$ python -m capa --run examples/grades.capa
=== Roster ===
  Ana: 17.5 (Excellent)
  Bruno: 13.0 (Pass)
  ...

$ python -m capa --transpile examples/hello.capa | head -20

Programmatic use

The compiler is also a library. The four-stage pipeline is exposed directly so you can embed any stage into a host program.

from capa import Lexer, Parser, analyze, transpile

source = open("program.capa", encoding="utf-8").read()
tokens = Lexer(source, filename="program.capa").lex()
module = Parser(tokens, source=source, filename="program.capa").parse_module()

result = analyze(module, source=source, filename="program.capa")
if not result.ok:
    for e in result.errors:
        print(e.format())
else:
    code = transpile(module, filename="program.capa")
    print(code)

Editor support

A VSCode extension lives in the vscode/ directory of the repository. It provides syntax highlighting (TextMate grammar), keywords by category, distinct colour for built-in capabilities, string interpolation, operator highlighting including .., ..=, =>, and ?. It is not on the VSCode Marketplace yet; install manually:

$ ln -s "$(pwd)/vscode" ~/.vscode/extensions/capa-language

PS> New-Item -ItemType Junction `
    -Path  "$HOME\.vscode\extensions\capa-language" `
    -Target "$PWD\vscode"

Reload VSCode and any .capa file will be highlighted. A full language server (diagnostics, hover, go-to-definition) is on the roadmap.

Where to go next