A programming language that reads like structured English and behaves like Python.
llang is built to be written by AI. It is deliberately highly interpretable and direct: every construct announces itself, every block has an explicit terminator, every argument is labeled, and nothing hidden or implicit can slip past a reviewer. The goal is not clever code β it is code you can read once and understand, so humans can review what an AI wrote with confidence.
Human-era compromises (terse syntax, abbreviations, operator soup, clever implicit behavior) are pure downside for a model, so llang trades them for verbose, explicit, regular constructs. Natural-language phrasing is the point, not a novelty β llang is structured pseudocode you can actually run.
set scores to a map with "Ada" mapped to 91, "Grace" mapped to 98
repeat for each student in (call keys of with collection = scores)
show student plus ": " plus (call text of with value = item student of scores)
end repeat
The language is implemented and usable. The primary execution path is the interpreter; a WebAssembly backend exists for the integer/function subset and is verified by executing its output in Node. For rewrites, "compiles" means the program parses, lints clean, and produces output identical to the original.
- Values: numbers, text, booleans,
nothing, lists, maps, functions - Statements:
set/let,show/display/print,require,add,set item,if/otherwise,repeat while,repeat for each,stop the loop,skip to the next item, functions with aliases, labeledcall,fail/expectproblem handling,usemodules - Expressions: strictly left-to-right with parentheses for grouping, word operators with closed synonyms (
floor divided byincluded), postfix predicates, collection literals, indexing, phrase-named builtins,applyfor calling function values - AI ergonomics: definitions may use phrase names (
define function find all ...), and@escapes reserved words anywhere a name is expected (taking @end,call f with @end = 1) - Domain libraries:
advanced_math(math/statistics),datascience(NumPy/pandas semantics),machinelearning(scikit-learn semantics) β all native llang, with self-describing results and loud validation - Libraries: native llang modules in
lib/(math,text,lists,shell,shlex,fnmatch,textwrap,csv,json,re,ast_contract,pylev,humanize), plus an explicitly labeled opt-in foreign bridge (json,math,shell) - Objects: minimal classes with explicit
this, single inheritance-free construction viacall new ..., andask instance to method ... - Compiler: a WebAssembly backend for the integer/function subset β
llang-compile file.ll -o file.wasm, verified by executing the output in Node - Self-hosting: the language's own lexer is written in llang (
lib/llang_lexer.ll) and verified token-for-token against the bootstrap lexer - Universal porting app: point it at a repository and it converts supported source files (Python, C, JavaScript) to readable llang, preserving structure, with coverage reports, verification, and a JSONL cleanup queue for AI-assisted completion β
llang-port-repo <repo> -o <out> - Tooling: source-located diagnostics, canonical formatter, pre-run linter, LSP language server, Python-to-llang converter, property-based differential fuzzer, single-command verification, GitHub Actions CI
- Ecosystem: native
jsonmodule, JSON package manifests with a registry, editor grammars for VS Code and tree-sitter, and a browser playground
The interpreter needs Python 3.10+ only. The full verification suite additionally
uses Node.js (for WebAssembly checks) and the Python data libraries used as
oracles: numpy, pandas, scikit-learn. Install them with
pip install -e '.[dev]' before running tools/check.py.
python run.py examples/hello.ll # run a program
python repl.py # interactive shell
python tools/check.py # every check: tests, lint, rewrites, links
python tools/port.py my.py -o ported.ll --report report.txt
python run.py --lint examples/hello.ll
python run.py --format examples/hello.ll
node tools/playground/server.js # browser playground at localhost:8080
python -m llang.portapp.cli <repo> -o <out> # port a whole repository to llang
Or install the package for console commands:
pip install -e .
llang examples/hello.ll
llang-port my.py -o ported.ll
llang-compile my.ll -o my.wasm
python -m llang.lsp # language server over stdio
Surface flexibility, canonical precision. The surface language has a closed vocabulary of synonyms; the parser normalizes every spelling to one canonical AST node, and the interpreter only ever sees that node. Synonyms add readability without adding ambiguity β the failure mode that sank AppleScript and Inform 7.
| Decision | Rule |
|---|---|
| Semantics | Grounded in authoritative docs of existing languages β re-express, never invent |
| Blocks | Explicit end if /end repeat /end function /end expect ; indentation ignored |
| Evaluation | Strictly left-to-right; parentheses for grouping |
| Types | Dynamic; strict operations, no implicit coercion |
| Arguments | Labeled roles ( call f with name = x ), never bare position |
| Extension | Libraries extend values and types, never syntax |
| Diagnostics | Source line/column and expected-token hints are part of the spec |
Start here:
- Tutorial β learn the language from zero
- Reference β complete authoritative reference
- Grammar β compact grammar that fits in an LLM prompt
- Examples β runnable programs with pinned output
Design and process:
- Design β decisions and rationale
- Semantic decisions β tricky choices and why
- Method β the repeatable process for adding a language surface
- Family plan β tiered IR, converter, libraries, build order
- Roadmap β honest scope and deferred features
- Rewrites β open-source Python software rewritten and verified in llang
- Research β grounded matrices: Python semantics, precedents, stdlib, demo, terminal, test plan
Project:
-
License β MIT
-
examples/report_card.llβ flagship program: a graded report card that checks its own result -
examples/rubiks.llβ Rubik's cube simulator that writes a browser viewer (rubiks.html) -
lib/shlex.ll,lib/fnmatch.ll,lib/textwrap.ll,lib/csv.ll,lib/json.ll,lib/re.llβ CPython modules rewritten in llang and verified against the stdlib -
lib/pylev.ll,lib/humanize.ll,lib/box2d.llβ external open-source repos cloned and rewritten, verified against the originals (1,562 cases);box2dis a headless physics engine subset with a working 60-step simulation -
examples/box2d_visual.llβ writesphysics.html, a live browser animation of that simulation (all frames computed in llang) -
lib/llang_lexer.llβ llang's own tokenizer, written in llang (self-hosting stage 2) -
lib/advanced_math.ll,lib/datascience.ll,lib/machinelearning.llβ domain libraries grounded in Python math/statistics, NumPy/pandas and scikit-learn (330 cases) -
2,546 differential cases total, 0 mismatches
-
src/llang/compiler.pyβ WebAssembly backend;tools/playground/β browser playground -
src/llang/lsp.pyβ language server;src/llang/packages.pyβ package manifests and registry -
editors/β VS Code and tree-sitter grammars;docs/SITE.mdβ documentation site guide -
tools/port.pyβ automated Python β llang converter with an honest coverage report -
src/llang/portapp/β universal repository porting app; seedocs/PORTING-APP.md -
tools/cleanup_prompt.pyβ turns a cleanup-queue item into a ready-to-paste AI prompt -
tools/check.pyβ one command for tests, lint, rewrite verification, and link checks
src/llang/ lexer, parser, canonical AST, interpreter, synonyms, errors,
formatter, linter, converter, WASM compiler, LSP, packages,
CLI entry points, foreign allowlist
lib/ standard library written in llang
examples/ runnable programs
tests/ unit, differential, diagnostics, end-to-end, compiler
docs/ reference and design documentation
docs/research/ grounding documents from authoritative external sources
tools/ port.py, check.py, compare_*.py, fuzz_semantics.py, playground,
fixtures, pilots
editors/ VS Code TextMate grammar and tree-sitter grammar
.github/ CI workflow and issue templates
run.py development CLI entry point
repl.py interactive shell