B4N1Lang | Jewels

Jewels

A jewel is a native modifier. It is one bubble on an entity — a named one — that replaces the boilerplate you would otherwise write by hand. This page answers the four questions every reader asks: what a jewel is, whether it is part of the language, whether you have to fetch it yourself, and whether you can write your own.

1. What is a jewel

The grammar has two kinds of bubble: the anonymous one, .(expr), and the named one, .name(args). A jewel is a named bubble whose behaviour is not implemented by the language itself but by a native artifact that the running program loads. In source there is no difference between a jewel and any other named bubble: same dot, same parentheses, same place in the pipeline.

self LatestPosts (lang: Str "en")
    .route("/{lang}/blog/")
    .(posts = db_scan("posts", "language=en,status=1", "date_posted", 1, 10, 0))
    .(html(render_string("blog/list.html", {"posts": posts})))

Two jewels appear above, as an example: .route serves the entity over HTTP, db_scan reads documents. The language does not know what either of them does — it knows how to call them.

2. It is not new syntax

A jewel never grows the grammar. That is the whole point: the language stays small and the catalogue grows. If you removed every jewel from a program the file would still parse; it would simply call functions nobody implements, and the compiler would say so before the program runs. A feature added to the language is a language feature; a capability added as a jewel is an artifact you can install, replace or write yourself.

3. You install it; it does not install itself

Nothing is downloaded behind your back. A program that uses a jewel needs that artifact present on the machine, and the program finds it at startup by looking, in this order, at your own plugins directory first:

Where it looksOrder
~/.config/b4n1/plugins/1 — yours, flat or one folder per jewel
B4N1_USER_PLUGIN_DIR2 — your own directories
B4N1_PLUGIN_DIR3 — where the installer puts them

A local copy of yours always wins over the one we ship: ours is a fallback, never an override of your choice. If the artifact is missing, the program stops and names the exact path it tried — it never pretends to work:

[b4n1] jewel 'guard': /home/you/.config/b4n1/plugins/guard/libb4n1_guard.so: cannot open shared object file: No such file or directory

Install one from the store, or from a directory you built yourself:

b4n1 plugin install guard
b4n1 plugin install ./my-jewel

4. New versions of the language do not bring new jewels silently

Jewels are independent artifacts with their own version. Updating the compiler or the runtime does not change the jewels you have, and a jewel you already installed keeps working until you replace it. That is deliberate: your program's behaviour cannot change because somebody else shipped a release. When a jewel gets faster or learns something new, you install the new version and you decide when.

The one thing the compiler does check is what your source declares. requires(\"...\") names the capability a program needs; the names travel into the binary as a list and are printed at startup, so a missing jewel is visible before the first request instead of at the first unlucky call.

requires("db")

5. Can you write your own jewel

Yes. A jewel is a plugin: one shared object exposing the same contract the shipped ones expose, plus a small manifest. Two versions of the contract exist and both must agree — the artifact declares which one it speaks, and the program checks it before borrowing a single function pointer, so an old artifact fails with a message naming both versions instead of crashing.

Install it from the folder and your program loads it exactly like ours. That is also how a capability we do not offer yet gets built: nobody has to wait for us.

6. Jewels are native; the browser has its own built-ins

A jewel runs where the native artifacts run. The browser module ships the language primitives — text, lists, maps, the operators — and a program that depends on a jewel belongs in the native binary. Same source, same semantics, different reach: the language does not change, only what the target can load.

The language itself, bubble by bubble · Run it in the browser