cf370564f3
A retrieval-ready knowledge base so an LLM can read/write Five without prior training: overview, syntax, full RTL catalog (from hbrtl/register.go), web/worker idioms (from the solmade app), and a long-tail gotchas file. Every doc has keyword/summary frontmatter; INDEX.md is the routing manifest. Grounded by parallel source exploration; RTL names spot-checked against register.go. The gotchas file is the compounding asset — append new traps. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
56 lines
3.2 KiB
Markdown
56 lines
3.2 KiB
Markdown
---
|
|
doc: five-overview
|
|
title: What Five is — model, philosophy, runtimes
|
|
keywords: [five, fivenode, overview, philosophy, token-density, harbour, xbase, compile, go, runtime]
|
|
summary: High-level orientation for an LLM about to read or write Five — what the language is, how it compiles, the two runtimes, and the design priorities (token density + Node/Go ecosystem).
|
|
---
|
|
|
|
# Five — orientation for an LLM
|
|
|
|
**Five** is an xBase/Harbour-compatible programming language that **compiles to Go**. You write `.prg` files in Harbour-family syntax; the Five toolchain generates Go and builds a native binary.
|
|
|
|
## Design priorities (why it exists)
|
|
|
|
1. **Token density** — express maximum functionality in minimum code. High-level verbs
|
|
(`PG_QUERY`, `AP_JSONRESPONSE`, `LLM_CHAT`, `hb_jsonDecode`) collapse what would be
|
|
dozens of lines of Go/Node boilerplate into one line. This is a *first-class* goal,
|
|
not an aesthetic: dense code means a whole system fits in an LLM context window, costs
|
|
fewer tokens per change, and exposes less surface area for bugs.
|
|
2. **No ecosystem isolation** — Five reaches the Go/Node ecosystem through the runtime
|
|
layer (RTL packages written in Go, blank-imported at build time). So you get dense
|
|
business logic *and* rich libraries (Postgres, HTTP, PDF, XLSX, LLM clients).
|
|
|
|
## Two distinct runtimes (do not confuse them)
|
|
|
|
| Path | What it is |
|
|
|------|-----------|
|
|
| `/Users/charleskwon/fivenode/fivedev/five` | **The Five language proper** — compiler (`compiler/lexer`, `parser`, `ast`, `gengo` Go codegen, `genpc`), runtime core (`hbrt`), and runtime library (`hbrtl`). CLI: `five run/build/gen <file.prg>`. |
|
|
| `/Users/charleskwon/fivenode/fivenode/fivenode_go` | **fivenode** — a separate runtime/toolchain (`fnode` compiler) used to build apps that lean on the Node/Go ecosystem (e.g. the `solmade` app). Distinct codebase from `fivedev/five`. |
|
|
|
|
When a task says "implement X in Five (the language)", it targets `fivedev/five`.
|
|
When building/running the `solmade` app, the `fnode` toolchain in `fivenode_go` is used.
|
|
|
|
## How a program is structured
|
|
|
|
- A `.prg` file contains `FUNCTION`/`PROCEDURE`/`STATIC FUNCTION` definitions.
|
|
- Execution entry is `Main()` (or `FUNCTION Main()` / `PROCEDURE Main()`).
|
|
- In the web app, **file-name routing** maps a URL to a function: `/api/foo-bar.prg`
|
|
→ the `Main()` in `app/api/foo_bar.prg`, dispatched as `FOO_BAR__MAIN`. (See idioms doc.)
|
|
|
|
## Compile model essentials (matters when writing code)
|
|
|
|
- The compiler **inlines common string intrinsics** (`LEN`, `CHR`, `ASC`, `SUBSTR`,
|
|
`LEFT`, `RIGHT`, `AT`, `PADR`, `PADL`) directly as Go in `compiler/gengo` — they do
|
|
NOT go through the `hbrtl` registry at runtime. Changing runtime behavior of these
|
|
requires editing the gengo intrinsics (they now call charset-aware `hbrtl.Str*`
|
|
helpers). See gotchas doc.
|
|
- Strings are **UTF-8 by default**; core string funcs operate on runes. A legacy charset
|
|
can be selected (`HB_SETCHARSET`/`HB_CDPSELECT`); env `FIVE_CHARSET`/`HB_CODEPAGE` sets
|
|
the initial charset.
|
|
|
|
## Where to look for ground truth
|
|
|
|
- Grammar/tokens: `compiler/lexer`, `compiler/parser`, `compiler/ast`.
|
|
- RTL function names: `hbrtl/register.go` (the registration table).
|
|
- Real idioms: the `solmade` app (`/Users/charleskwon/solmade/app/**/*.prg`).
|