B4N1Lang | The Sovereign Language

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

DeclarationMeaning
name: Intrequired integer
name: Int 0integer with default 0
name: Str ""text with a default (Str is the canonical form; String is accepted too)
name: Float 0.0float with default
name: Bool falseboolean with default
name: Listlist 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)

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

CallEffectWhere it runs
.concat(s)join two texts (+ NEVER concatenates)everywhere, including the browser
.join(sep)a list of text becomes one text, sep between elementseverywhere, including the browser
len(s)character count (elements for lists)everywhere, including the browser
str(x) / int(x)convert between text and integerseverywhere, including the browser
.upcase() .downcase()change casenative binaries (jewel)
.strip() .replace(a, b)trim, substitutenative binaries (jewel)
.split(sep)split into a listnative 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
  |         ^
CodeMeaning
E0101syntax error (position with caret)
E0102input file does not exist (no caret)
E0103unsupported 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).