⚒️ Forge

The internet-native programming language that reads like English.

Built-in HTTP, databases, crypto, AI, and a JIT compiler. 18 modules. 238+ functions. No extra packages required.

📥 Download Book · 📖 Language Spec · 🌐 Website · 💬 Discussions · 🐛 Issues

---

brew install humancto/tap/forge    # install
forge learn                        # 30 interactive tutorials
forge run app.fg                   # run a program

---

⚡ See It In Action

REST API — 3 lines, zero deps

@server(port: 3000)

@get("/hello/:name")
fn hello(name: String) -> Json {
    return { greeting: "Hello, {name}!" }
}

Database + Crypto — built in

db.open(":memory:")
db.execute("CREATE TABLE users (name TEXT)")
db.execute("INSERT INTO users VALUES ('Alice')")

let users = db.query("SELECT * FROM users")
term.table(users)

say crypto.sha256("password")

No framework. No packages. No setup. Just forge run.

---

📖 Table of Contents

⚡ Quick Example	🎯 Why Forge?	📦 Installation
🗣️ Dual Syntax	🚀 Quick Tour	🏗️ Type System
📚 Standard Library	⚡ Performance	🎮 GenZ Debug Kit
🔧 CLI	📂 Examples	🏛️ Architecture
📕 Book	🗺️ Roadmap	🤝 Contributing

---

🎯 Why Forge?

Modern development means installing dozens of packages before writing a single line of logic:

# Python: pip install flask requests sqlalchemy bcrypt python-dotenv ...
# Node:   npm install express node-fetch better-sqlite3 bcrypt csv-parser ...
# Go:     go get github.com/gin-gonic/gin github.com/mattn/go-sqlite3 ...

Forge: everything is built in.

Task	Forge	Python	Node.js	Go
REST API server	3 lines	12 + flask	15 + express	25 lines
Query SQLite	2 lines	5 lines	8 + better-sqlite3	12 + go-sqlite3
SHA-256 hash	1 line	3 lines	3 lines	5 lines
HTTP GET request	1 line	3 + requests	5 + node-fetch	10 lines
Parse CSV	1 line	4 lines	6 + csv-parser	8 lines
Terminal table	1 line	5 + tabulate	4 + cli-table	10 + tablewriter
Retry with backoff	1 line	12 + tenacity	15 + async-retry	20 + retry-go

💡 Forge ships with 0 external dependencies needed for HTTP, databases, crypto, CSV, regex, terminal UI, shell integration, AI, and more.

---

📦 Installation

# Homebrew (macOS & Linux) — recommended
brew install humancto/tap/forge

# Cargo (Rust)
cargo install forge-lang

# Install script
curl -fsSL https://raw.githubusercontent.com/humancto/forge-lang/main/install.sh | bash

# From source
git clone https://github.com/humancto/forge-lang.git && cd forge-lang && cargo install --path .

Verify:

forge version          # → forge 0.4.3
forge learn            # 30 interactive tutorials
forge                  # start REPL

---

🗣️ Dual Syntax

Write it your way. Both compile identically.

✦ Natural — reads like English

set name to "Forge"
say "Hello, {name}!"

define greet(who) {
    say "Welcome, {who}!"
}

set mut score to 0
repeat 5 times {
    change score to score + 10
}

if score > 40 {
    yell "You win!"
} otherwise {
    whisper "try again..."
}

⚙ Classic — familiar syntax

let name = "Forge"
println("Hello, {name}!")

fn greet(who) {
    println("Welcome, {who}!")
}

let mut score = 0
for i in range(0, 5) {
    score += 10
}

if score > 40 {
    println("You win!")
} else {
    println("try again...")
}

Concept	Classic	Natural
Variables	let x = 5	set x to 5
Mutable	let mut x = 0	set mut x to 0
Reassign	x = 10	change x to 10
Functions	fn add(a, b) { }	define add(a, b) { }
Output	println("hi")	say / yell / whisper
Else	else { }	otherwise { } / nah { }
Async	async fn x() { }	forge x() { }
Await	await expr	hold expr
Structs	struct Foo { }	thing Foo { }
Methods	impl Foo { }	give Foo { }
Interfaces	interface Bar { }	power Bar { }
Construct	Foo { x: 1 }	craft Foo { x: 1 }
Fetch	fetch("url")	grab resp from "url"
Loops	for i in range(0, 3) { }	repeat 3 times { }
Destruct	let {a, b} = obj	unpack {a, b} from obj

---

🚀 Quick Tour

Variables & Functions

let name = "Forge"              // immutable
let mut count = 0               // mutable
count += 1

fn add(a, b) { return a + b }
let double = fn(x) { x * 2 }   // lambda with implicit return

🎤 The Output Trio

say "Normal volume"              // standard output
yell "LOUD AND PROUD!"          // UPPERCASE + !
whisper "quiet and gentle"       // lowercase + ...

Control Flow & Pattern Matching

if score > 90 { say "A" }
otherwise if score > 80 { say "B" }
otherwise { say "C" }

// When guards
let label = when temp {
    > 100 -> "Boiling"
    > 60  -> "Warm"
    else  -> "Cold"
}

// Algebraic data types + pattern matching
type Shape = Circle(Float) | Rect(Float, Float)
match Circle(5.0) {
    Circle(r) => say "Area = {3.14 * r * r}"
    Rect(w, h) => say "Area = {w * h}"
}

🔑 Innovation Keywords

safe { risky_function() }                         // returns null on error
must parse_config("app.toml")                     // crash with clear message
check email is not empty                          // declarative validation
retry 3 times { fetch("https://api.example.com") } // automatic retry
timeout 5 seconds { long_operation() }             // enforced time limit
wait 2 seconds                                     // sleep with units

Collections & Functional

let nums = [1, 2, 3, 4, 5]
let result = nums
    .filter(fn(x) { x % 2 == 0 })
    .map(fn(x) { x * 2 })
say result   // [4, 8]

let user = { name: "Alice", age: 30 }
say pick(user, ["name"])            // { name: "Alice" }
say get(user, "email", "N/A")      // safe access with default

Error Handling

fn safe_divide(a, b) {
    if b == 0 { return Err("division by zero") }
    return Ok(a / b)
}

match safe_divide(10, 0) {
    Ok(val) => say "Got: {val}"
    Err(msg) => say "Error: {msg}"
}

// Propagate with ?
fn compute(input) {
    let n = parse_int(input)?
    return Ok(n * 2)
}

---

🏗️ Type System

Define data types, attach behavior, enforce contracts, and compose with delegation.

✦ Natural — thing / give / power

thing Person {
    name: String,
    age: Int,
    role: String = "member"
}

give Person {
    define greet(it) {
        return "Hi, I'm " + it.name
    }
}

power Describable {
    fn describe() -> String
}

give Person the power Describable {
    define describe(it) {
        return it.name + " (" + it.role + ")"
    }
}

set p to craft Person { name: "Alice", age: 30 }
say p.greet()                      // Hi, I'm Alice
say satisfies(p, Describable)      // true

⚙ Classic — struct / impl / interface

struct Person {
    name: String,
    age: Int,
    role: String = "member"
}

impl Person {
    fn greet(it) {
        return "Hi, I'm " + it.name
    }
}

interface Describable {
    fn describe() -> String
}

impl Describable for Person {
    fn describe(it) {
        return it.name + " (" + it.role + ")"
    }
}

let p = Person { name: "Alice", age: 30 }
println(p.greet())                 // Hi, I'm Alice
println(satisfies(p, Describable)) // true

Composition with has

thing Address { street: String, city: String }
thing Employee { name: String, has addr: Address }

give Address {
    define full(it) { return it.street + ", " + it.city }
}

set emp to craft Employee {
    name: "Charlie",
    addr: craft Address { street: "123 Main St", city: "Portland" }
}

say emp.city        // delegated to emp.addr.city → "Portland"
say emp.full()      // delegated to emp.addr.full() → "123 Main St, Portland"

Keyword	Purpose
thing / struct	Define a data type
craft	Construct an instance
give / impl	Attach methods to a type
power / interface	Define a behavioral contract
has	Embed a type with field + method delegation
it	Self-reference in methods
satisfies(obj, Power)	Check if an object satisfies a contract

---

📚 Standard Library (18 Modules)

Every module is available from line 1. No imports. No installs.

🌐 HTTP Server & Client

// Server — 3 lines to production
@server(port: 3000)
@get("/users/:id")
fn get_user(id: String) -> Json {
    return db.query("SELECT * FROM users WHERE id = " + id)
}

// Client — just fetch
let resp = fetch("https://api.github.com/repos/rust-lang/rust")
say resp.json.stargazers_count

🗄️ Database (SQLite + PostgreSQL + MySQL)

db.open(":memory:")
db.execute("CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT)")
db.execute("INSERT INTO users (name) VALUES ('Alice')")
let users = db.query("SELECT * FROM users")
term.table(users)

// MySQL — parameterized queries, connection pooling
let conn = mysql.connect("mysql://root:pass@localhost/mydb")
let users = mysql.query(conn, "SELECT * FROM users WHERE age > ?", [21])
mysql.close(conn)

🔐 JWT Authentication

let token = jwt.sign({ user_id: 123, role: "admin" }, "secret", { expires: "1h" })
let claims = jwt.verify(token, "secret")
say claims.user_id       // 123
say jwt.valid(token, "secret")  // true

🐚 Shell Integration

say sh("whoami")                           // quick stdout
let files = sh_lines("ls /etc | head -5")  // stdout as array
if sh_ok("which docker") { say "Docker installed" }
let sorted = pipe_to(csv_data, "sort")     // pipe Forge data into shell

🖥️ Terminal UI

term.table(data)                   // formatted tables
term.sparkline([1, 5, 3, 8, 2])   // inline charts ▁▅▃█▂
term.bar("Progress", 75, 100)     // progress bars
say term.red("Error!")             // 🔴 colored output
say term.green("Success!")         // 🟢
term.banner("FORGE")               // ASCII art banner

🔐 Crypto + 📄 CSV + 📁 File System

say crypto.sha256("forge")                    // hash anything
say crypto.base64_encode("secret")             // encode/decode

let data = csv.read("users.csv")               // parse CSV files
csv.write("output.csv", processed_data)         // write CSV

fs.write("config.json", json.stringify(data))   // file I/O
let exists = fs.exists("config.json")

Module	Functions
math	sqrt, pow, abs, sin, cos, tan, pi, e, random, random_int, clamp, floor, ceil, round
fs	read, write, append, exists, list, mkdir, copy, rename, remove, size, lines, dirname, basename, join_path, is_dir, is_file, temp_dir
crypto	sha256, md5, base64_encode/decode, hex_encode/decode
db	SQLite — open, query, execute, close (parameterized queries supported)
pg	PostgreSQL — connect, query, execute, close (parameterized queries supported)
mysql	MySQL — connect, query, execute, close (parameterized queries, connection pooling)
jwt	sign, verify, decode, valid (HS256/384/512, RS256, ES256)
json	parse, stringify, pretty
csv	parse, stringify, read, write
regex	test, find, find_all, replace, split
env	get, set, has, keys
log	info, warn, error, debug
term	colors, table, sparkline, bar, banner, box, gradient, countdown, confirm, menu
http	get, post, put, delete, patch, head, download, crawl
io	prompt, print, args_parse, args_get, args_has
exec	run_command
time	now, format, parse, sleep, elapsed
npc	Fake data — name, email, username, phone, number, pick, bool, sentence, id, color, ip, url, company

---

⚡ Performance

Three execution tiers — pick your tradeoff:

Engine	fib(30)	vs Python	Best For
🔥 --jit	10ms	11x faster	Compute-heavy hot functions
⚙️ --vm	252ms	~2x slower	General bytecode execution
📦 Interpreter	2,300ms	~20x slower	Full feature set + all 238+ functions

Language	Time	Relative
Rust 1.91 (-O)	1.46ms	baseline
C (clang -O2)	1.57ms	~1.1x
Go 1.23	4.24ms	~2.9x
Scala 2.12 (JVM)	4.33ms	~3.0x
Java 1.8 (JVM)	5.77ms	~4.0x
JavaScript (Node 22/V8)	9.53ms	~6.5x
Forge (JIT)	10ms	~7x
Python 3	114ms	~79x
Forge (VM)	252ms	~173x
Forge (interpreter)	2,300ms	~1,575x

The JIT compiles hot functions to native code via Cranelift, placing Forge alongside Node.js/V8 for recursive workloads.

Server	Req/sec	Avg Latency	vs Python
Forge (axum + interpreter)	28,017	7.1 ms	9.8x faster
Rust / Axum (native async)	24,853	8.0 ms	8.7x faster
Python / Flask (threaded)	2,854	70.0 ms	1.0x

Forge's HTTP server is built on axum + tokio — the same stack powering production Rust services. For typical JSON API endpoints, Forge matches raw Rust throughput while giving you a 4-line handler instead of 40.

Tested with ApacheBench (ab -n 20000 -c 200) on localhost, macOS. Run your own:

# Terminal 1
forge run examples/bench_server.fg

# Terminal 2
forge run examples/bench_client.fg     # Forge-native client with stats
ab -n 20000 -c 200 http://127.0.0.1:9090/ping   # or use ab/wrk/oha

---

🎮 GenZ Debug Kit

Debugging should have personality. Forge ships both classic and GenZ-flavored debug tools.

sus(my_object)         // 🔍 inspect any value (= debug/inspect)
bruh("it broke")       // 💀 crash with a message (= panic)
bet(score > 0)         // 💯 assert it's true (= assert)
no_cap(result, 42)     // 🧢 assert equality (= assert_eq)
ick(is_deleted)        // 🤮 assert it's false (= assert_false)

Plus execution tools:

cook { expensive_op() }           // ⏱️ profile execution time
slay 1000 { fibonacci(20) }      // 📊 benchmark (1000 iterations)
ghost { might_fail() }           // 👻 silent execution (swallow errors)
yolo { send_analytics(data) }    // 🚀 fire-and-forget async

---

🔧 CLI Commands

Command	What It Does
forge run <file>	Run a program
forge	Start REPL
forge -e '<code>'	Evaluate inline
forge learn [n]	30 interactive tutorials
forge new <name>	Scaffold a project
forge test [dir]	Run tests
forge fmt [files]	Format code
forge build <file>	Compile to .fgc bytecode
forge build --native <file>	Build a native launcher executable
forge install <src>	Install a package
forge lsp	Language server
forge chat	AI assistant
forge version	Version info

---

📂 Examples

forge run examples/hello.fg        # basics
forge run examples/natural.fg      # natural syntax
forge run examples/types.fg        # type system — thing/give/power/craft/has
forge run examples/api.fg          # REST API server
forge run examples/data.fg         # data processing + visualization
forge run examples/devops.fg       # system automation
forge run examples/showcase.fg     # everything in one file
forge run examples/functional.fg   # closures, recursion, higher-order
forge run examples/adt.fg          # algebraic data types + matching
forge run examples/result_try.fg   # error handling with ?
forge run examples/jwt_demo.fg     # JWT authentication
forge run examples/mysql_demo.fg   # MySQL database CRUD

---

🏛️ Architecture

Source (.fg) → Lexer → Tokens → Parser → AST → Type Checker
                                                     ↓
                            ┌────────────────────────┼────────────────────────┐
                            ↓                        ↓                        ↓
                       Interpreter              Bytecode VM              JIT Compiler
                     (full features)           (--vm flag)             (--jit flag)
                            ↓                        ↓                        ↓
                     Runtime Bridge            Mark-Sweep GC          Cranelift Native
                  (axum, reqwest, tokio,       Green Threads              Code
                   rusqlite, postgres)

~26,000 lines of Rust. Zero unsafe blocks in application code.

Crate	Purpose
axum	HTTP server
tokio	Async runtime
reqwest	HTTP client
cranelift	JIT compilation
rusqlite	SQLite
ariadne	Error reporting
rustyline	REPL
clap	CLI parsing

---

📕 The Book

---

📊 Project Status

Forge is v0.4.3. The language, interpreter, and standard library are stable; VM/JIT backends are fast but still subset runtimes.

Metric	Value
Lines of Rust	~27,000
Standard library modules	18
Built-in functions	238+
Keywords	80+
Tests passing	1,275 (644 Rust + 631 Forge)
Interactive lessons	30
Example programs	18
Dependencies (CVEs)	344 crates (0 CVEs)

Known Limitations

[!NOTE] Forge is a young language. These are documented, not hidden.

• Parameterized SQL queries supported — pass a params array as the second argument to db.query, db.execute, pg.query, pg.execute, and mysql.query / mysql.execute to safely bind user input and prevent SQL injection.
• Three execution tiers with different trade-offs — The interpreter is the full language runtime. Use --vm for supported bytecode execution, --jit for integer-heavy hot paths, and --profile to inspect VM execution.
• VM/JIT feature gap — VM and JIT now fail fast on unsupported language features instead of silently compiling partial behavior. Use the default interpreter for full stdlib, HTTP, database, AI, and advanced language features.
• forge build --native is a launcher today — it produces a native executable wrapper that shells back into the Forge runtime. Standalone AOT binaries are still on the roadmap.
• regex functions take (text, pattern) argument order, not (pattern, text).

---

🗺️ Roadmap

Version	Focus
v0.3 ✅	Type system (thing/power/give/craft/has), 73 new functions, GenZ debug kit, NPC module, 822 tests
v0.4 ✅	JWT auth, MySQL, parameterized SQL (all DBs), CORS, PG TLS, 18 modules, 1,019 tests
v0.5	Backend parity, package foundations, richer LSP
v0.6	Stronger typing, permissions, profiling and benching
v0.7	Standalone native compilation groundwork
v1.0	Stable API, compatibility guarantees, production hardening

Near-term execution focus: semantic parity across backends, package/module correctness, stronger typing, better editor tooling, and a path from launcher-based native builds to real standalone binaries.

See ROADMAP.md for the public roadmap. Have ideas? Open an issue.

---

✏️ Editor Support

VS Code — Syntax highlighting available in editors/vscode/:

cp -r editors/vscode ~/.vscode/extensions/forge-lang

LSP — Built-in language server:

forge lsp

Configure your editor's LSP client to use forge lsp as the command.

---

🤝 Contributing

git clone https://github.com/humancto/forge-lang.git
cd forge-lang
cargo build && cargo test
forge run examples/showcase.fg

See CONTRIBUTING.md for the architecture guide and PR guidelines. See CODE_OF_CONDUCT.md for community standards.

---

🔒 Security

To report a security vulnerability, please email the maintainers directly instead of opening a public issue. See SECURITY.md.

---

📄 License

MIT

---

Stop installing. Start building.

Built by HumanCTO · GitHub · LinkedIn