Files

CharlesKWON cf370564f3 docs(rag): Five knowledge corpus for LLM agents

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>

2026-06-15 13:54:03 +09:00

3.2 KiB

Raw Blame History

doc, title, keywords, summary

doc

title

keywords

summary

five-overview

What Five is — model, philosophy, runtimes

five

fivenode

overview

philosophy

token-density

harbour

xbase

compile

runtime

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)

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.
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).

3.2 KiB Raw Blame History