j.joa/docs Experimental
Docs/Getting started
THE JOA LANGUAGE

Getting started

Build the Joa interpreter with Go, write your first .jo program, and run native IPv4 and subnet examples on Windows, macOS, or Linux.

Joa runs .jo source files with a small interpreter written in Go. Build it from source, then run your first program.

Prerequisites

Install Go 1.22 or later and Git. Check your Go installation with go version. Node.js is only needed to develop this documentation website, not to run Joa.

Get the source

git clone https://github.com/Berlindraft/Joa.git
cd Joa

Build the interpreter

On Windows PowerShell:

go build -o joa.exe .
.\joa.exe examples\hello.jo

On macOS or Linux:

go build -o joa .
./joa examples/hello.jo

You can also run a file without building a separate executable:

go run . examples/hello.jo

Run these commands from the repository root, where go.mod lives. No third-party Go modules are required.

Write your first program

Create first.jo in the repository root:

let name = "world"
print("Hello, " + name + "!")

fn double(n) {
    return n * 2
}

print(double(21))

Run it with go run . first.jo:

Hello, world!
42

Use let to declare a variable, fn for a function, and braces for blocks. Newlines separate statements; semicolons are optional.

Work with your network

IP addresses and subnets are literal values. Leave the quotes off to use the native types:

let office = 10.10.0.0/16
let client = 10.10.5.42

print(type(client))
print(client in office)
print(office.network)
print(office.split(18)[0])
IP
true
10.10.0.0
10.10.0.0/18

CLI behavior

The command accepts a source path: joa <file.jo>. With no path, it prints its version and usage. A file read, lexing, parsing, or runtime error exits with status 1. Successful runs exit with status 0. There is no interactive REPL or command-line package manager.

If joa is not found, use the executable’s relative path (.\joa.exe or ./joa) or add its directory to your PATH. If a source file cannot be opened, check its path relative to your current directory.

Where to go next