B4N1Lang (.bl)
The sovereign language. self is the context anchor and the body is a sequence of assignments — the last .(expr) bubble is the entity output. Because every call is a bubble, the same logic reads as one inline chain or as named steps: both forms are the same program.
1. Define an entity
self — the mandatory context anchor. Entity names are PascalCase by convention. The last .(expr) bubble is the entity output — there is no return keyword.
When does an entity run? Three ways: a route serves it (.route), the top-level script calls it, or job mode invokes it (B4N1_JOB_FN=Name). The top-level script IS the program: its bubbles run top to bottom, print, and the process exits — exactly like a script with no entities. An entity nobody calls compiles but does nothing.
.lock(x = 5) .mut(x = 5) .(x = 5)
Everything is a bubble. Assignments ride inside an anonymous bubble: .(x = value) is the only statement form. Declarations are NAMED bubbles — .lock(x = value) / .mut(x = value), the same family as .route and .docs. lock rejects any later assignment to the name, loudly.
2. Parameter types
| Declaration | Meaning |
|---|---|
| name: Int | required integer |
| name: Int 0 | integer with default 0 |
| name: Str "" | text with a default (Str is the canonical form; String is accepted too) |
| name: Float 0.0 | float with default |
| name: Bool false | boolean with default |
| name: List | list of text — a list literal argument converts element by element |
A declared default fills omitted arguments: a call like .(hola()) uses the declared defaults, and job mode (B4N1_JOB_FN) calls with them too. Defaults must be literals (Int/Float/Str/Bool) — anything else is a loud compile error.
3. Chaining (pipeline)
| Operator | Effect |
|---|---|
| . | sequential chain (output → input) |
| .. | fork: a branch of the current fork |
| :: | merge: closes the fork |
The pipeline today is the dot: each .(expr) bubble receives the previous stage's output. Fork and merge split and close the flow (see 3g); error-interceptor bubbles (.! / .!?) are still on the roadmap, and the docs never teach what the compiler does not accept.
3b. Inheritance — .from(Base) and map merge
self Child (n: Int)
.from(Base)
.(n * 2)
.from(Base) runs Base with ALL the arguments Child received, before the child's own body — the bubble is hoisted to the front of the body wherever it was written. One base per entity; .from twice or inheriting from yourself are loud errors. Data inheritance is + on maps: the right operand's keys override the left's (child fields win over base fields), new keys inherit.
3c. Lists as parameters — name: List
self First (xs: List)
.(xs[0])
.(First([1, 2, 3]))
.(First(["a", "b"]))
Those two runs answer 1 and a. A declared List parameter is a list of text: the call site converts each element of the argument list through its text form, so a numeric literal [1, 2, 3] arrives as text rows and xs[0] reads the element back. A list passed to a scalar parameter (Int/Float/Str) is a loud compile error — the compiler never flattens a list into a value.
3d. Decimal — bank-grade exact fixed-point
self Sum (a: Decimal, b: Decimal)
.(a + b)
.(Sum(0.10, 0.20))
.(Sum(19.99, 0.01))
Those two runs answer 0.30 — never 0.30000000000000004 — and 20.00. A declared Decimal parameter is an exact fixed-point decimal built on a scaled 128-bit integer, with zero external dependencies. Decimal literals keep their source scale (0.10 stays two decimals), add/subtract/multiply are exact, and division rounds half-up at the larger operand scale — declare the operands with the scale you need. Comparisons compare by value (19.9 equals 19.90). Division by zero and malformed decimal text fail loudly.
3e. Buffer — raw bytes
self tam (b: Buffer)
.(len(b))
.(tam("hola"))
That run answers 4. A declared Buffer parameter is a raw byte sequence in the compiled backend. A text argument is converted to its UTF-8 bytes at the call site; indexing yields the byte widened to an integer and len() counts bytes. Indexing past the end yields the byte 0 — defined behavior, never a silent crash. A list passed to a Buffer parameter is a loud compile error — the compiler never guesses byte values.
3f. Lambda — inline functions with =>
.(doble = (x: Int => x * 2)) .(doble(21))
That run answers 42. A lambda defines a one-line function inside an assignment bubble, at the script level (never inside an entity). The body is a single expression; untyped parameters are inferred from their use. An inline lambda in a call argument is a loud error with a hint — lambdas are supported only as .(name = (params => expr)) definitions.
3g. Fork & merge — ..(name = expr) and ::(expr)
self Resumen (n: Int)
.(base = n * 2)
..(a = base + 1)
..(b = base + 2)
::(a + b)
.. splits the flow: every ..(name = expr) branch binds a channel with the state at the fork point. Channels are independent — a later branch reading an earlier channel is a loud error. :: closes the fork and must consume the channels: ::(expr) is the block output, ::(name = expr) captures the value and keeps the block going. Forks work at the script level, inside entities, inside for bodies and inside if branches; a fork without its merge, a merge without a fork and a merge that consumes no channel are all loud errors.
self DosForks (n: Int)
..(a = n + 1)
::(r1 = a * 2)
..(b = n + 2)
::(r2 = b * 3)
::(r1 + r2)
4. Control flow
Block headers take no colon — the body is plain assignments and the last .(expr) bubble is the output (there is no return keyword). Jewel bubbles like .route chain on the entity. A nested call chain can stay inline or be broken into named steps — bubbles make both forms equivalent.
5. Operators
+ - * / arithmetic NUMBERS only — + NEVER concatenates strings == != < > <= >= and or not
To concatenate strings use .concat(). Mixing + with text fails at compile time with an explicit error — never a silent concat.
6. Jewels (native modifiers)
A jewel is a native modifier: one bubble on the entity that replaces the boilerplate you would otherwise write. Jewels are not part of the language grammar — the grammar says a bubble is .(...) and a named bubble is .name(args); a jewel is one of those names, resolved to a native artifact. Which jewels exist, where they come from and how they are installed is a catalogue of its own: the jewels page. This page documents the language, so it names none of them.
Two consequences worth knowing before you read that page: the language never chooses a jewel for you, and a program that uses one needs the artifact present — otherwise it fails loud, naming the exact path it looked in.
7. Documentation bubbles
.docs("Renders the blog index.")
.todo("add pagination")
self Index (n: Int 5)
.route("/blog/")
.comment("inline note")
.logs("served from cache")
.(n)
Everything is a bubble — even the comments. There is no hashtag syntax floating outside the grammar: .docs documents, .todo tracks pending work, .comment and .logs mean nothing. All four are first-class, always parseable, and cost zero bytes in the binary. Run b4n1 docs app.bl and the reference comes back: one card per entity with its signature, routes, docs and TODOs.
8. Maps and lists
Maps are written literally with string keys and read with square brackets; a missing key reads as an empty string unless you give .get() a default. Lists index with integers and len() counts their elements.
Dijkstra over five nodes with the edges held as parallel lists — a whole graph search in bubbles, no library, no imports. It runs in the browser too.
9. Text
| Call | Effect | Where it runs |
|---|---|---|
| .concat(s) | join two texts (+ NEVER concatenates) | everywhere, including the browser |
| .join(sep) | a list of text becomes one text, sep between elements | everywhere, including the browser |
| len(s) | character count (elements for lists) | everywhere, including the browser |
| str(x) / int(x) | convert between text and integers | everywhere, including the browser |
| .upcase() .downcase() | change case | native binaries (jewel) |
| .strip() .replace(a, b) | trim, substitute | native binaries (jewel) |
| .split(sep) | split into a list | native binaries (jewel) |
The jewel column is the honesty rule: the browser player runs the core subset only, so the docs never offer a Run button the browser cannot honor. The notebook is the playground: it compiles your edited source to WebAssembly INSIDE the browser (the compiler core itself is a .wasm module — no server, no toolchain). Long text beyond 256 bytes: text(x) builds an unbounded value.
10. Build a web page
A web app is entities with routes. .route(path) mounts the entity on the HTTP server the compiled binary IS; render_string fills an HTML template with a context map; html(body) answers with it (html(body, status) sets an explicit status, redirect(url, code) sends a real Location header).
self ProductPage (slug: Str "")
.route("/en/product/{slug}/")
.(ctx = {"slug": slug, "title": "Product"})
.(rendered = render_string("product.html", ctx))
.(html(rendered))
Read-only here: serving HTTP needs the full native runtime — compile the binary and open the port. The site you are reading is itself a compiled b4n1lang app.
11. Read data (one jewel, as an example)
The db jewel scans documents by filter, sorts and paginates without SQL: db_scan(collection, filter, sort, page, limit, offset) returns a list of maps. Writes go through db_put / db_create / db_del.
self LatestPosts (lang: Str "en", limit: Int 10)
.route("/{lang}/blog/")
.(posts = db_scan("posts", "language=en,status=1", "date_posted", 1, limit, 0))
.(html(render_string("blog/list.html", {"posts": posts})))
Read-only here: the db is a native jewel (SQLite storage behind it), not part of the browser subset.
12. Compile pipeline
.bl → Lexer → Parser → AST → Audit → Codegen → Native binary / WASM module
b4n1 compile app.bl app — compile to a self-contained native binary. b4n1 compile --mode wasm app.bl app.wasm — the browser module from the same source. b4n1 run app.bl — compile and execute. b4n1 docs app.bl — generate the reference for a source file. Every compile also runs the embedded security scan automatically.
13. Errors
An error says what and where. Codes are stable, positions are 1-based, and the caret points at the offending token:
error[E0101]: unexpected token in expression: Eq --> app.bl:3:9 | 3 | y = = 2 | ^
| Code | Meaning |
|---|---|
| E0101 | syntax error (position with caret) |
| E0102 | input file does not exist (no caret) |
| E0103 | unsupported extension (only .bl / .blang) |
A valid program produces no diagnostics at all.
▶ Open the notebook — the playground: chained cells that compile and run in your browser. ⬇ Download the offline playground — one self-contained file with the whole compiler + every example inside: save it, double-click it, and the full playground runs with no network, no server and no toolchain (the page itself stays light: the compiler core loads lazily on your first keystroke or Run).