[English](README.md) | [PortuguΓͺs](README.pt_BR.md)
# Kof
### One language. One compiler. Many worlds.
pronounced coffe
**Less code. More intention. JVM, native, script and web. All starting from the same language.**
---
## Mascot
Kof's mascot is a **civetta** β also known as the **musk cat**,
it is a feline that eats coffee. Nothing more fitting for a language
pronounced *coffe*.
---
## Disclaimer
The Kof language has no relationship whatsoever with the game The King of Fighters or its franchise.
The name Kof came about as a reference to the word "coffee" deliberately spelled incorrectly. The choice was made precisely in an attempt to create a short, unique and easily identifiable name for the language.
Koflang and Kof4J do not endorse the association of the name with the The King of Fighters franchise. Any similarity or association made in that sense is incidental and does not represent the origin, purpose or identity of the projects.
Our goal has always been to create a unique identity for the language and its components.
---
> Some people look at a problem and write a library.
>
> Others write a framework.
>
> Some create a tool.
>
> I apparently looked at the entire ecosystem and thought:
>
> **"This is all too complicated. I'm going to create a language."**
>
> And, apparently, a language alone wasn't enough either.
Welcome to **Kof**.
---
# What is Kof?
Kof is a **general-purpose, statically typed** programming language, built around one central idea:
> **A single language should not force you to choose a single world.**
> π **The formal language specification** (grammar, type system,
> semantics, status of each feature) is in
> [`docs/language-reference/`](docs/language-reference/). The compiler
> architecture (implementation) is in
> [`docs/architecture/compiler-architecture.md`](docs/architecture/compiler-architecture.md). The
> distinction **language β compiler β target** is the axis of those documents.
Kof has its own compiler, lexer, parser, type system, semantic analysis and intermediate representation (Kof IR). From that IR, different backends turn the same program into different forms of execution:
```text
Kof Language (defined by the specification)
β
Kof Compiler (one implementation)
β
Kof IR (linear stack machine, 30 ops)
β
βββββββββββββββββΌβββββββββββββββββ
β β β
JVM Backend Native Backend JS Backend
β β β
βΌ βΌ βΌ
JVM Native Binary ES Modules
(.class) (ELF x86_64, (Node /
riscv64/aarch64) browser)
```
**The language does not change. The target changes.** JVM, Native and JS are
*compilation targets* of the same Kof β not semantically different dialects.
**KofScript** (`.ks`, REPL) is a *direct execution target*: pure Kof consuming
the SAME frontend and executed by the IR interpreter, without compiling and
without a JVM fork β **it is not JavaScript** (`let`/`const`/`async`/`fn` do
not exist). KofC is a separate tool (C subset β ELF), it does not consume the
Kof IR β see
[docs/architecture/compiler-architecture.md](docs/architecture/compiler-architecture.md) Β§7.)
---
# Kof is not a transpiler
Kof does not work like this:
```text
Kof β Java β javac β JVM
```
It works like this:
```text
Kof β Kof Compiler β Kof IR β Backend β Target
```
The compiler has its own implementation of:
* lexer
* parser
* AST
* symbol resolution
* type system
* semantic analysis
* IR
* diagnostics
* code generation
Kof does not depend on Java as an intermediate language.
---
# Current State
Kof is in active development β **0.3.0-beta**.
The compiler has its own frontend, type system, Kof IR and **three backends
over the IR**, which produce **six targets**: JVM (V21 via ASM), Native x86_64
(ELF, no libc), `native.risc`/`native.arm` (real riscv64 + aarch64 via
ISA translator), KofJS (ES Modules) and Android (JVM variant + APK packaging).
**KofScript** (`.ks`, REPL) is a **direct execution target**: pure Kof
on the SAME frontend, executed by the IR interpreter (`KofInterpreter`) without
emitting bytecode or a JVM fork. **KofC** (C subset β native) is a separate
tool, it does not consume the Kof IR β see
[docs/architecture/compiler-architecture.md](docs/architecture/compiler-architecture.md) Β§7.
| Feature | JVM | Native | KofJS |
|---------|-----|--------|-------|
| println, variables, arithmetic | β
| β
| β
|
| if/else, if-expr, while, for, for-in, switch | β
| β
| β
|
| functions (without `fun`), lambdas with captures | β
| β
| β
|
| records, classes, inheritance, interfaces, virtual dispatch | β
| β
| β
|
| generics (erasure), `Box` with primitives | β
| β
| β
|
| exceptions (throw "msg", try/catch/finally) | β
| β
| β
|
| null safety `String?` + narrowing | β
| β
| β
|
| pattern matching `case String s` + record destructuring | β
| β
| β
|
| spawn/await (`Handle`, unboxing) | β
| β
(pthread) | β
sequential |
| strings (concat `+`, `==`, full API) | β
| β
| β
|
| arrays, `List`/`Map`/`Set` + map/filter/reduce | β
| β
| β
|
| enums + exhaustive switch | β
| β
| β
|
| JSON encode/decode (objects/records/arrays, 3 targets) | β
| β
| β
|
| kof.io (File, Path, Directory) | β
| β
| β
|
| kof.time (`now`/`sleep`/`interval`), kof.cache | β
| β
| β
|
| kof.web (`web.app()`, ws, sse, TLS) | β
| WEB002 | WEB001 |
| kof.http client + retry/circuit | β
| HTTP002 | β
|
| kof.security (passwords, crypto, jwt, secrets, auth) | β
| β
| β
|
| kof.db / kof.orm (native SQLite, MySQL WIP, MongoDB) | β
| β
| DB001/ORM001 |
| kof.config / kof.log | β
| β
| CONF001/LOG001 |
| kof.ui (Color, Palette, Theme, widgets) | no-op | no-op | β
render |
**Concurrency**: `spawn task()` / `val r = spawn f(); await r` β virtual
threads on the JVM, `pthread_create` on Native (CONC001 closed 31/08),
sequential on JS (CONC003). See [docs/language-reference/concurrency.md](docs/language-reference/concurrency.md).
**Null safety**: `String?`/`Int?` + `if (x != null)` narrowing on the 3 targets
(JVM fix 02/09). `Map.get` returns `V?` for reference values.
**Tests**: `test "name" { }` + `assert(cond, "msg")` + `kof test` β 810 tests
(793 kof-compiler + 8 kof-script + 5 kof-c-compiler + 4 kof-cli). See
[learn/23-testing.md](learn/23-testing.md).
**Debugging**: `kof debug ` β DAP server over stdio with raw JDWP
(breakpoints by Kof line, call stack with Kof functions/lines, continue,
disconnect). See [docs/debugging/debugging.md](docs/debugging/debugging.md).
**Ecosystem audit**: stdlib coverage matrix (inventory,
gaps G1-G12, priority and strategy) in
[docs/bugs-and-gaps/ecosystem-coverage.md](docs/bugs-and-gaps/ecosystem-coverage.md). Evolution plan
toward a complete platform: [docs/development/roadmap.md](docs/development/roadmap.md).
---
# kof.ui β The UI platform
Kof's UI foundation: `Color` (32-bit RGBA), `Palette` (named colors)
and `Theme` (light/dark with semantic colors) β same semantics on JVM,
Native and JS. Rendering is **KofJS**: widgets β real DOM in the native
webview (`bin/kof-webview`, embedded WebKitGTK) or in the browser.
Widgets: `Window` (title, bind, show/close, size, theme), `Label` (text,
fontSize, bold, color), `Button` (text + action via lambda with captures),
`Input` (text), `Column`/`Row` containers, `View`+`Style` (background,
padding, radius).
```kof
class App {
static Int count = 0
}
main() {
var w = Window("Contador")
var label = Label("contagem: 0")
w.bind(label)
w.bind(Button("+1", () -> {
App.count = App.count + 1
label.text = "contagem: " + App.count
}))
w.show()
}
```
```bash
kof run contador.kf --target=js # opens the window; closing ends the program
```
See: [learn/35-kof-ui.md](learn/35-kof-ui.md) and
[learn/37-kofjs.md](learn/37-kofjs.md).
---
# Documentation β where to look for what
| Folder | For whom | What it contains |
|-------|-----------|--------------|
| [`docs/`](docs/) | architects, maintainers, decisions | **Technical and project documentation**: current state (`status.md`, `backend-parity.md`; snapshots in `history/`), architecture (`architecture/`), philosophy (`philosophy.md`), stdlib and areas (`stdlib/` β includes security, http, web, config, database, logging, observability), concurrency (`language-reference/`), language (`language-reference/`), debugging (`debugging/`), comparison (`comparison/`), runtime (`runtime/`), roadmap (`development/roadmap.md`), targets (`targets/`), UI (`ui/`), distribution and license (`distribution/`), consolidated design decisions (`decisions/`), tooling (`tooling/`), future visions (`development/future/`) and audits (`development/ecosystem-coverage.md`, `architecture/complexity-audit.md`) |
| [`learn/`](learn/README.md) | humans learning Kof | **Learning track in numbered chapters** (00 Introduction β 39 stdlib): language, classes, functions, lambdas, UI, security β each chapter a hands-on guide; `learn/native/` for the native target |
| [`training/`](training/README.md) | LLMs and AI tools | **Structured corpus optimized for language models**: facts by topic (`language/`), idioms (`idioms/`), patterns/anti-patterns (`patterns/`, `anti-patterns/`), compilable examples (`examples/`), reference (`reference/`), JavaβKof migration (`migration/`), tooling and releases |
**Rule of thumb**: `docs/` says *how Kof is* (state and architecture);
`learn/` teaches *how to use Kof* (step by step); `training/` feeds
*those who generate Kof code* (LLMs).
---
# kof.web β Native Web Stack
Web applications without Spring, without a servlet container, without annotations:
```kof
record User(String name, Int age)
main() {
var app = web.app()
app.use {
if (header("x-auth") == "secret") {
return null
}
return "{\"error\": \"unauthorized\"}"
}
app.get("/hello") {
return "Hello from Kof"
}
app.get("/users/:id") {
return "user " + param("id") + " q=" + query("name")
}
app.post("/user") {
var user = json.decode(body())
return json.encode(user)
}
app.listen(8080)
}
```
```bash
kof serve app.kf
```
Path params, query, headers, body, middleware, typed JSON and an HTTP server
embedded in the program's runtime. See: [docs/stdlib/stdlib-web.md](docs/stdlib/stdlib-web.md).
---
# kof.io β Filesystem
Files, directories and paths with a single API across all targets:
```kof
var path = Path("data/users.txt")
path.parent().createDirectories()
path.writeText("Mel\nKof\n")
println(path.readText())
println(path.size())
```
```kof
var dir = Directory("data")
dir.createDirectories()
for (var entry in dir.list()) {
println(entry.name)
}
```
Text always UTF-8; bytes as `Int[]`; absence as `String?` (`null`) and
`size()` throws instead of a `-1` sentinel. See: [learn/34-file-system.md](learn/34-file-system.md) and
[docs/stdlib/IO.md](docs/stdlib/IO.md).
---
# Installation
Kof is a **distribution**: install it and get the compiler, CLI, runtime,
stdlib, tooling, editor support and an embedded OpenJDK. **No external
Java installation is required** β and you don't need to know the version to install.
1. Download the package for **your** system from
[GitHub Releases](https://github.com/KofLang/Kof4j/releases/latest):
`linux-x86_64.tar.gz` / `macos-arm64.tar.gz` / `windows-x86_64.zip`.
2. Extract it and add `bin` to `PATH`:
```bash
# Linux
tar -xzf kof-*-linux-x86_64.tar.gz
export PATH="$PWD/$(ls -d kof-*-linux-x86_64 | head -1)/bin:$PATH"
# macOS (Apple Silicon)
tar -xzf kof-*-macos-arm64.tar.gz
export PATH="$PWD/$(ls -d kof-*-macos-arm64 | head -1)/bin:$PATH"
# Windows (PowerShell)
Expand-Archive .\kof-*-windows-x86_64.zip
$DIR = (Get-ChildItem -Directory -Filter "kof-*-windows-x86_64" | Select-Object -First 1).FullName
$env:PATH = "$DIR\bin;$env:PATH"
```
3. Check it:
```bash
kof version # kof
kof info # full environment (embedded JVM, Tooling API 21, targets)
```
See: [docs/distribution/INSTALL.md](docs/distribution/INSTALL.md) (complete
guide with each system, checksum and troubleshooting) and
[docs/distribution/ARCHITECTURE.md](docs/distribution/ARCHITECTURE.md).
---
# CLI
```bash
kof build [--target jvm|native|native.risc|native.arm|js|android] [--output ] [--release]
kof run [--target jvm|native|native.risc|native.arm|js] [args...]
kof serve [--port ] [--host ]
kof check [--json]
kof test [--target jvm|native|js]
kof script | repl | c | fmt | config
kof bench | profile | inspect | debug
kof info | lsp | install | version
```
`kof fmt` (idempotent formatter) and `kof config gen` implemented β see
[docs/tooling/README.md](docs/tooling/README.md).
---
---
# Building and installing from source
**Requirements:** **JDK 25** (Temurin recommended β the repo build baseline
since D-BASELINE 14/09; `--release 25`) and Maven 3.9+. For the `native`
target: `as`/`ld` (binutils). The `js` target requires nothing external
(GraalJS embedded in the jar).
> **Three JDK layers, do not confuse them (D-BASELINE):**
> - **Building this repo:** JDK **25** required (`pom.xml` `release=25`; the
> compiler code uses unnamed patterns `_` = JEP 443, finalized in 22 β JDK
> 21 cannot compile the sources).
> - **Running the `kof` CLI:** the classes are `release 25`, so the CLI itself
> runs on JDK **25**; `scripts/package.sh --jdk` embeds Temurin 25 so the
> packaged distribution carries its own JVM.
> - **Your Kof programs (the LANGUAGE contract β frozen, rule 6):** unchanged.
> The JVM backend still emits **`V21`** bytecode (`JvmBackend`) and the
> Android template still targets `release 21`, so a `.kf` you compile runs on
> **JVM 21+**. Raising the repo toolchain does NOT raise the language's
> minimum runtime.
```bash
# 1. Build everything (compiler, runtime, CLI with embedded GraalJS)
mvn clean package -DskipTests
# 2. Run the full suite (JVM + Native + KofJS E2E)
mvn test
# 3. Use straight from source (dev build, system java)
mkdir -p lib
cp kof-cli/target/kof-cli-$(cat VERSION).jar lib/kof.jar
bin/kof version
bin/kof info
# 4. Install into a prefix (full local installation)
bin/kof install ~/.kof
export PATH="$HOME/.kof/bin:$PATH"
kof version
# 5. Package the official distribution (with embedded OpenJDK 25)
scripts/package.sh --jdk # generates dist/kof---.tar.gz
```
`kof install ` copies `kof.jar` to `/lib/` and generates the launcher
`/bin/kof` (it uses the embedded JDK from `/jdk/` when present; otherwise the
system `java`). `scripts/package.sh --jdk` downloads Temurin 25 from
Adoptium and assembles the complete distribution layout.
Versioning centralized in `VERSION` β see
[docs/distribution/VERSIONING.md](docs/distribution/VERSIONING.md).
**Windows:** use **Git Bash** for `scripts/package.sh` β the generic `bash`
in `PATH` may resolve to WSL and generate a Linux distribution
(OBS-005). On Windows, Python may only be available as the launcher `py` β
the script discovers it automatically (`python3`/`python`/`py -3`).
---
# Architecture
```text
Source (.kf)
β Lexer
β Parser
β AST
β Type System
β Semantic Analysis
β Kof IR (backend-agnostic)
βββ JVM Backend (ASM) β .class
βββ Native Backend (x86_64 / riscv64 / aarch64) β ELF
βββ JS Backend (GraalJS) β ES Modules
```
---
# Principles
1. Less code, same capability
2. Strong typing
3. Intention over ceremony
4. One frontend, multiple backends
5. Straight to the target
6. Interoperability
7. No unnecessary magic
8. Tools matter
## The "paradigm" of intention
Kof is **intention-oriented** β which is not a formal paradigm, but rather
object orientation taken to the extreme: the code expresses *what* it wants, and
the platform (language + compiler + runtime + stdlib) decides *how*, per
target and per convention.
```text
intention β Kof β compiler β backend
```
You write `spawn task()` (not `Thread`), `app.get("/users/:id")` (not a
servlet container), `Window`/`Button("+1", () -> ...)` (not WebView/JavaFX),
`json.decode(body)` (not a manual parser), `Palette.red` (not
`0xFF0000FF`). If it is essential to any program, it belongs to the platform.
When a target cannot fulfill the intention, it says so at
compile-time with a gap code (`CONC001`, `JSN002`, ...) β never
silently.
Details: [docs/philosophy.md](docs/philosophy.md) Β· idioms:
[training/idioms/](training/idioms/) Β· anti-patterns:
[training/anti-patterns/](training/anti-patterns/).
---
# What Kof is NOT
* Java with another syntax.
* Kotlin 2.
* Julia for the JVM.
* A transpiler.
* A Java generator.
* An interpreter disguised as a compiler (the compiler is real: bytecode/ELF/ESM; `KofInterpreter` is an additional direct execution target, not a disguise).
Kof is a language. A compiler. An IR. Several backends.
---
# License
Kof is free software distributed under the **GNU General Public License v3.0**.
This applies to the compiler source code, tools and other project components.
**Programs written in Kof are NOT automatically GPLv3.**
The author of a program retains the right to choose the license for their own software. Using the Kof compiler does not obligate anyone to open their source code.
Proprietary software written in Kof is allowed, as long as it respects the licenses of the dependencies it actually incorporates.
For more details, see [docs/distribution/LICENSING.md](docs/distribution/LICENSING.md).
---
**Kof**
*One language. One compiler. Many worlds.*
*Less ceremony. More intention.*