# Broadsword

*A programming language for people who want to see the machine, not hide from it.*

## What is it?

Broadsword is a small, verb-first programming language that compiles straight down to 
machine code — no virtual machine, no interpreter, no bytecode, no runtime library sitting 
between your program and the operating system. You write a `.bs` file, run it through the 
`bsc` compiler, and you get a standalone binary that talks to the Linux kernel directly.

If you've never heard of it, that's fair — it's a one-person project, still young, and not 
trying to be the next mainstream language. It's closer in spirit to something like Lua or 
C in terms of scale and directness, but with its own syntax lineage: it reads more like 
COBOL or early BASIC than like C or Python. Verbs come first. Sentences read almost like 
instructions you'd give a person: `SUM [A] AND [B] TO [C]`. `FIND "&" IN [SUBMISSION] TO [POSITION]`.

## Why does it exist?

Most modern languages add layers between you and the hardware — garbage collectors, package
managers, runtime environments, frameworks on top of frameworks. Each layer buys convenience,
but it also buys distance. You stop knowing what your program is actually doing at the level
of memory and syscalls, because you don't need to know, because something else is handling it for you.

Broadsword goes the other way on purpose. There's no hidden allocator, no invisible runtime 
doing things behind your back, no framework you have to learn before you can learn the 
language. What you write is close to what actually executes. The tradeoff is real — you 
do more by hand, and the standard library is small because there isn't one — but the
payoff is a kind of clarity that's gotten rare: when something breaks, you can usually
see exactly why, because there's nowhere for the bug to hide.

There's also a retrocomputing thread running through the project. Part of the long-term
ambition is a compiler that can target genuinely old or constrained hardware — machines
that were never meant to run anything written today, but still have a CPU and some RAM
and deserve to be useful again.

## What does it actually look like?

A short taste — checking a value and branching:

```
WHEN [STATUS] EQUALS #0 SEEK [ALL_CLEAR]
SEEK [HANDLE_ERROR]
```

Reading a file, byte by byte, until it's done:

```
STEP [READLOOP]
    FILE-READ [HANDLE] TO [CHUNK]
    STATUS [BYTES]
    WHEN [BYTES] ZERO SEEK [DONE_READING]
    SAY [CHUNK]
    SEEK [READLOOP]
DONE
```

No semicolons, no curly braces, no indentation rules. Code is organized into named `STEP`
blocks, and control flow is explicit jumps (`SEEK`) rather than nested `if`/`while` 
structures. It's a flatter mental model than most languages ask for — closer to reading
a flowchart out loud than reading an expression tree.

## What can you build with it?

Despite being a small project, it's not just a toy — real, working programs have been 
built and deployed in it, including:

- A **Gopher server**, serving real requests over the internet
- A **CGI backend** powering a live website guestbook
- An **IRC client** that connects to real chat networks
- Small interactive console-style web tools

It compiles for standard x86-64 Linux today, with an additional flat-binary target for
embedded/microcontroller work in progress.

## What makes it different from the language you already know?

- **No garbage collector, no hidden runtime** — closer to C's philosophy of "what you 
write is what runs," but with a syntax that reads more like structured English than symbol-heavy C.
- **No object-oriented anything** — no classes, no inheritance, no methods. Just 
verbs, variables, and jumps.
- **Deliberately small surface area** — there isn't a sprawling standard library 
to learn before you can be productive. What the language can do is mostly what you 
can see in its verb list.
- **One person's compiler, built from scratch** — tokenizer, symbol table, and code
emitter all written by hand, without leaning on existing compiler infrastructure like LLVM.

## Is it for you?

Probably, if any of this sounds appealing: you like knowing exactly what your code
is doing at the level of memory and system calls; you find something satisfying about
small, explicit, unglamorous tools; you've ever wanted to write something for
hardware that modern languages have quietly stopped caring about; or you just 
like the idea of a language that reads more like a set of instructions than a puzzle to be solved.

It's not going to replace Python for scripting or Rust for systems work with safety
guarantees — it isn't trying to. It's a different kind of tool, for a different 
kind of satisfaction: watching a program you wrote in plain, verb-first sentences 
turn directly into bytes a CPU executes, with nothing in between.