Jennifer

Jennifer is a small, experimental, interpreted programming language written in (Tiny)Go and ships as two binaries:

• jennifer - standard Go build, full host-feature surface. This is the default binary you install and reach for.
• jennifer-tiny - TinyGo build, smaller and embeddable. Missing os/exec and the network stack (TinyGo runtime gaps); calls into those surfaces return a friendly runtime error pointing back at jennifer. Use this variant when binary size or embeddability matters (embedded systems, minimal containers, small-footprint scripting hosts).

But small is not bare. Jennifer is batteries-included: a broad standard library and a growing set of distributable modules cover what real programs actually need, so you build genuine tools, not toys. Text handling has full regular expressions; structured data flows through JSON; email is a complete stack - SMTP to send, POP3 and IMAP to receive; in-memory data stores come through Redis and memcached clients; the web runs from an ergonomic REST client to turnkey integrations such as Gotify push notifications; and lightweight concurrency is built into the language via spawn and the task library. Browse the full library catalog and module catalog - both grow with every release.

It is also a natural fit for teaching and learning: an interactive REPL, an easy-to-read grammar, and token and AST dumps that make it ideal for mastering language design, plus a built-in linter and profiler and full test support. Its strict, explicit design - conditions must be bool, conversions are spelled out, names never shadow, and errors are positioned - surfaces a mistake as a clear message instead of a silent surprise, so a learner sees exactly what went wrong.

Source files use the .j extension. Whitespace is not significant anywhere; statements end with ;.

use io;
use time;

def start as time.Time init time.now();
io.printf("hello, world\n");
def gap as time.Duration init time.sub(time.now(), $start);
io.printf("ran for %d ms\n", time.milliseconds($gap));

Write Jennifer with your editor and an AI assistant

Syntax highlighting ships in editors/ (a Vim / Neovim drop-in, a TextMate grammar for VS Code / Sublime / Zed, a highlight.js definition). And because Jennifer is new, we ship JENNIFER.md: drop it into your project and point an AI coding assistant at it (“we code in Jennifer, see JENNIFER.md, let’s go”) so it writes correct .j from the start. See Editor & AI support.

What’s in this site

• Getting started - install the interpreter and run your first program.
• Editor & AI support - highlighting and the drop-in JENNIFER.md for AI-assisted coding.
• Language reference - syntax, types, methods, control flow, imports, style.
• Libraries - per-library reference plus an alphabetical cheatsheet of every builtin.
• Modules - the Jennifer-coded, importable module ecosystem (import "name.j";): formats, mail, stores, web, and protocol clients, each with its own reference page.
• Technical reference - implementation details for the lexer, parser, interpreter, and CLI.
• Project - milestones, design stances, glossary.

Status

Pre-1.0. The major version stays at 0.x.y while the language is still finding its shape; breaking changes can happen at milestone boundaries and are called out in docs/milestones.md. Once Jennifer reaches 1.0.0, semver applies and breaking changes need a major bump.

Source

Source, issues, and pull requests live at https://github.com/jennifer-language/jennifer.

License: LGPL-3.0-only.

Manual

Download the whole manual as a single PDF. The entire documentation in one file, regenerated from these pages on every build - handy for reading or searching offline.

Installing & running

Which binary?

On Linux (the supported platform) Jennifer ships as two binaries. Same source, same language; only the compiler differs. Pick by use case:

Both binaries install side by side and never overlap. The packaged distributions below install both; for tarball or from-source builds you get both binaries in one go too. (The best-effort macOS / Windows builds ship the standard jennifer only - see macOS / Windows below.)

Install

Debian / Ubuntu (.deb)

Pick the right .deb for your architecture from the latest Releases page, verify the checksum, and install:

# Replace X.Y.Z with the release version, e.g. 0.14.0
ARCH=$(dpkg --print-architecture)   # amd64 or arm64
curl -LO "https://github.com/jennifer-language/jennifer/releases/download/X.Y.Z/jennifer_X.Y.Z_${ARCH}.deb"
curl -LO "https://github.com/jennifer-language/jennifer/releases/download/X.Y.Z/jennifer_X.Y.Z_${ARCH}.deb.sha256"
sha256sum -c "jennifer_X.Y.Z_${ARCH}.deb.sha256"
sudo dpkg -i "jennifer_X.Y.Z_${ARCH}.deb"

Installs /usr/bin/jennifer + /usr/bin/jennifer-tiny, man pages under /usr/share/man/man1/, bash completion, the XDG MIME definition that registers .j as text/x-jennifer with file managers and editors, and Vim + Neovim syntax highlighting (dropped in both /usr/share/vim/vimfiles and /usr/share/nvim/site so .j files highlight with no per-user setup in either editor). A Sublime Text / bat syntax also ships at /usr/share/jennifer/syntaxes/jennifer.sublime-syntax; bat needs a one-time activation (copy it into $(bat --config-dir)/syntaxes/ and run bat cache --build) since it compiles syntaxes into a per-user cache.

Arch Linux (AUR)

Two packages, take whichever fits:

# Prebuilt binary, downloads the release tarball (fast install):
yay -S jennifer-bin
# or paru -S jennifer-bin, or any other AUR helper.

# Builds from source on each install, tracks main:
yay -S jennifer-git

Both install the same set of files as the .deb. The jennifer-bin package is on par with each release; jennifer-git rebuilds against the latest commit on main whenever you ask your AUR helper to upgrade.

Linux (tarball)

For distros without a native package, grab the per-arch tarball from the Releases page:

# Replace X.Y.Z and ARCH with the release version + your arch
curl -LO "https://github.com/jennifer-language/jennifer/releases/download/X.Y.Z/jennifer-X.Y.Z-linux-${ARCH}.tar.gz"
tar -xzf "jennifer-X.Y.Z-linux-${ARCH}.tar.gz"
cd "jennifer-X.Y.Z-linux-${ARCH}"
./jennifer version
./jennifer-tiny version

The tarball lays out as:

jennifer-X.Y.Z-linux-ARCH/
├── jennifer              # standard-Go binary (default)
├── jennifer-tiny         # TinyGo binary (constrained)
├── README.md
├── JENNIFER.md
└── share/
    ├── man/man1/         # jennifer.1, jennifer-tiny.1
    ├── mime/packages/    # jennifer.xml (XDG MIME)
    ├── bash-completion/  # completions/jennifer (+ jennifer-tiny symlink)
    ├── vim/vimfiles/     # syntax/ + ftdetect/ (Vim highlighting)
    ├── nvim/site/        # syntax/ + ftdetect/ (Neovim highlighting)
    └── jennifer/syntaxes/ # jennifer.sublime-syntax (Sublime Text / bat)

To install system-wide:

sudo install -m 0755 jennifer      /usr/local/bin/
sudo install -m 0755 jennifer-tiny /usr/local/bin/
sudo install -m 0644 share/mime/packages/jennifer.xml /usr/local/share/mime/packages/
sudo update-mime-database /usr/local/share/mime || true

macOS / Windows (unsupported)

Linux is the only supported platform. As a convenience, best-effort unsupported binaries for macOS (Intel + Apple Silicon) and Windows (64- and 32-bit) are attached to each release, named ...-UNSUPPORTED. Read the caveats before relying on them:

• Best-effort, may be absent. They come from a pipeline step that is allowed to fail; if a build breaks, that release simply won’t have them, and it does not hold up the Linux release.
• Standard jennifer only. No jennifer-tiny - TinyGo’s macOS / Windows host support is too limited to ship. This is the full-featured build, so os.run / os.spawn, the net library, and the rest of the surface all work.
• Unsigned. On macOS, Gatekeeper quarantines the download - clear it with xattr -d com.apple.quarantine ./jennifer (or right-click -> Open). On Windows, SmartScreen warns about an unknown publisher - choose “More info” -> “Run anyway”.
• No support. Bugs specific to macOS / Windows may not be fixed; supported development and testing happen on Linux. Fully supported builds for these platforms are separate future work (see milestones.md).
• Just the binary. No installer, man pages, MIME registration, or shell completion off Linux - the archive holds the executable plus JENNIFER.md, README.md, and the licence.

Windows 8.1 and earlier are not possible: this project’s Go toolchain (Go 1.21+) produces binaries that require Windows 10 or newer (or Windows Server 2016+). Go discontinued support for older releases in Go 1.21, so Windows 7, 8, and 8.1 - as well as Vista and XP - are all excluded, not just XP. The 32-bit build targets 32-bit Windows 10 / 11.

Build from source

For development, or any platform without a prebuilt artifact. You need a working TinyGo toolchain plus standard Go. From the repository root:

# Build both binaries:
make build

# Or just one:
make build-go      # produces ./jennifer      (standard Go, default)
make build-tinygo  # produces ./jennifer-tiny (TinyGo, constrained)

# Quick iteration without rebuilding:
go run ./cmd/jennifer run examples/hello.j

The make targets regenerate internal/version/version_gen.go from git state before invoking the toolchain, so ./jennifer version always reflects the current commit. See ../libraries/meta.md for the meta.VERSION string format.

Running

# Run a Jennifer source file (.j extension required):
jennifer run examples/hello.j

# Print the build version:
jennifer version

You can also pipe source in on stdin by passing - as the filename:

echo 'use io; io.printf("hi\n");' | jennifer run -
jennifer run - < program.j
cat program.j | jennifer run -

When reading from stdin, error messages identify the source as <stdin> and file imports (include "name.j";) resolve relative to the current working directory.

Interactive REPL

For experimenting with the language, start an interactive session with jennifer repl:

$ jennifer repl
jennifer - Jennifer programming language interpreter
type :quit (or Ctrl-D) to exit; :help for help
>>> use io;
>>> def x as int init 21;
>>> $x + $x;
42
>>> io.printf("hi\n");
hi
>>> func dbl(n as int) {
...   return $n * 2;
... }
>>> dbl(7);
14
>>> :quit

A few notes:

• Statements still end with ;. If a line ends with an unclosed { or (, the prompt switches to ... and waits for you to finish the block.
• A bare expression at the end of an input (like $x + $x;) prints its value. null results (including the return value of printf) are suppressed.
• String results are printed with surrounding double quotes so they’re distinguishable from numbers ("hello", not hello).
• Variables, constants, methods, and library imports persist for the whole session. Methods can be redefined freely as you iterate.
• File splices (include "lib.j";) work in the REPL and resolve relative to the directory you launched jennifer repl from.
• :quit, :exit, or Ctrl-D end the session; :help shows a reminder.

The prompt supports the standard line-editing keys you’d expect from a modern shell:

History is in-memory only (no on-disk persistence yet) and holds up to 100 entries. When stdin is piped (e.g. echo ... | jennifer repl in a test harness) the editor is bypassed and the REPL reads lines normally, so non-interactive uses keep working.

Inspection and formatting

Three commands help you see what Jennifer is doing under the hood and keep your source in canonical shape:

# Print the lexer's token stream, one per line
jennifer tokens examples/hello.j

# Print the parsed (and preprocessed) AST as JSON
jennifer ast examples/hello.j

# Reformat the source to canonical style (see style-guide.md)
jennifer fmt examples/hello.j

fmt writes the formatted source to stdout. To rewrite in place, use your shell: jennifer fmt foo.j > foo.j.new && mv foo.j.new foo.j. The formatter is idempotent (fmt of fmt output equals fmt output) and preserves runtime behavior - every example in this repo is checked both ways by the test suite. See style-guide.md for the full style rules.

Your first program

Save the following as hello.j:

# hello.j
use io;

def x as int init 21;
io.printf($x + $x);

Run it:

./jennifer run hello.j

You should see 42.

What just happened

1. use io; makes Jennifer’s standard library functions available.
2. def x as int init 21; declares an integer variable named x and initializes it to 21. Notice that using a variable requires the $ prefix.
3. io.printf($x + $x) calls the standard library function with the result of 21 + 21.

Top-level statements run in source order - there is no required entry-point method. You can still group reusable code into methods (def) and call them explicitly.

Editor support and AI-assisted coding

Two things make writing Jennifer outside this repo comfortable: syntax highlighting in your editor, and a drop-in language reference so an AI coding assistant can write correct Jennifer for you. Both ship in the repository.

Editor syntax highlighting

Highlighting definitions live in editors/. Jennifer’s lexical rules are regular enough that highlighting is genuinely accurate - $x is always a variable, UPPER_CASE a constant, NS.name a namespaced call, # and /* */ comments.

• Vim / Neovim - a true drop-in. Copy editors/vim/syntax/jennifer.vim and editors/vim/ftdetect/jennifer.vim into ~/.vim/ (or ~/.config/nvim/); .j files are detected automatically.
• VS Code / Sublime Text / Zed - use the TextMate grammar editors/textmate/jennifer.tmLanguage.json (scope source.jennifer) from a thin language extension.
• bat / Sublime Text - the native editors/sublime/jennifer.sublime-syntax. For bat, copy it into $(bat --config-dir)/syntaxes/ and run bat cache --build (it caches syntaxes per user, so a system path can’t auto-activate it).
• Static sites / blogs - the highlight.js definition registers a jennifer language.

Per-editor install steps are in editors/README.md.

One caveat: GitHub’s Linguist assigns the .j extension to Objective-J, so GitHub’s web UI will not highlight Jennifer source as Jennifer. That is a GitHub-side limitation; local editors and self-hosted sites are unaffected.

Jennifer as a shell filter

jennifer run - reads a program from stdin, so Jennifer slots into a pipe like any other filter. A handy one is a json-pretty that reformats JSON flowing through it. Save the program to a file (say ~/.local/share/jennifer/json-pretty.j):

use json;
use io;

def src as string init "";
while (not io.eof()) {
    $src = $src + io.readLine() + "\n";
}
io.printf("%s\n", json.encodePretty(json.decode($src)));

then alias it:

alias json-pretty='jennifer run ~/.local/share/jennifer/json-pretty.j'

echo '{"b":2,"a":1}' | json-pretty
curl -s https://api.example.com/thing | json-pretty

Swap json for any other decode / re-encode pair to get, for example, a pretty-xml. A no-file variant that pipes the program itself through jennifer run - is in the CLI reference.

AI-assisted coding with JENNIFER.md

Jennifer is new and small, so a general-purpose AI assistant has no built-in knowledge of it and will otherwise guess (usually Python-with-dollar-signs). JENNIFER.md is a single, self-contained language reference written for exactly this: drop it into your project and point your assistant at it.

We're coding in Jennifer, a small interpreted language. Read JENNIFER.md
for the syntax and standard library, then let's build ...

It covers the lexical rules (the $ sigil, letters-only identifiers, UPPER_CASE constants), types, operators (including / being float division), control flow, methods, concurrency, imports, the namespaced standard library, and a checklist of the mistakes an assistant most often makes. It describes the language, not the interpreter internals, and stays in sync with this spec.

It doubles as a human quick-reference. For the exhaustive per-function detail behind it, see the library reference and cheatsheet.

Jennifer - User Guide

Jennifer is a small, experimental, interpreted programming language. This guide covers everything you can do in Jennifer. Run jennifer version to see which build you’re on; the language history lives in docs/milestones.md.

Design stances

A handful of decisions shape every feature in Jennifer. Read them before the topical chapters - they explain why the language looks the way it does and rule out the “but why don’t you just…” reflex.

See docs/design-stances.md for the full seven-stance table.

Contents

• Installing & running - building the binary, running a program, the interactive REPL, the inspection and formatting commands.
• Your first program - a one-screen hello.j and a walkthrough of what each line does.
• Editor & AI support - syntax highlighting for your editor, and the drop-in JENNIFER.md that lets an AI assistant write Jennifer.
• Syntax - tokens, comments, identifier rules.
• Types and values - the primitive types, variables and constants, scoping rules, and the compound types list and map.
• Methods - declaring methods, parameters, return values, recursion, hoisting, the no-shadowing rule for builtins.
• Control flow - operators, precedence, if / while / for / for-each.
• Imports - use LIB; for libraries, import "file.j"; for source files, the library catalog.
• Examples - small programs that exercise the language end-to-end.
• Style guide - the canonical source style that jennifer fmt produces; the spacing/indentation rules, the names convention, the [] and {} literal layout.
• Best practices - stylistic guidance and code-smell heuristics for writing Jennifer that ages well. Not enforced by the language; click through if you want the “why”.

Related

• docs/libraries/ - one reference page per standard library (io, convert, math, strings, …).
• docs/modules/ - the Jennifer-coded modules that ship with the interpreter, brought in with import (ansi, csv, mime, redis, …).
• docs/technical/ - interpreter internals for contributors.
• docs/glossary.md - canonical project terminology. When two words could plausibly name the same concept (function vs method, library vs module, list vs array), this page picks the one the project uses everywhere.
• docs/milestones.md - what’s shipped, what’s planned.

Syntax

Tokens and whitespace

Whitespace (spaces, tabs, newlines) is not significant anywhere in Jennifer. The lexer skips it between tokens and never reads it from inside one. Statements are terminated by ;, blocks by matched { / } - never by indentation or line breaks. The same program can be written across many lines or jammed onto one, and it parses the same:

# canonical form
use io;
def x as int init 21;
io.printf("%d\n", $x + $x);

# all three statements on one line - same program
use io; def x as int init 21; io.printf("%d\n", $x + $x);

# split across many lines - also the same program
use   io
;
def
    x
        as
            int
                init
                    21 ;
printf (
    "%d\n"
    ,
    $x
        +
            $x
)
;

The same flexibility applies to qualified (namespaced) calls. All three of these print the host OS and are accepted by the parser:

use io;
use os;

io.printf(os.JENNIFER_OS);            # canonical - tight everywhere
io.printf( os.JENNIFER_OS );          # ugly - spaces inside the call parens
printf   (   os     . JENNIFER_OS  );   # uglier - spaces around `.` too

The third form parses fine because the . between os and JENNIFER_OS is just another token boundary - the lexer doesn’t care that there are spaces around it. jennifer fmt rewrites all three into the canonical form, so you’ll only ever see the first one after a format pass. The style guide makes “no space around .” explicit, but it’s a style rule, not a syntax rule.

A few practical consequences worth knowing up front:

• jennifer fmt is the enforcement layer for style. The style guide describes the canonical shape (one space around binary operators, no space inside ( / [ / {, 1TBS braces, tight . in qualified calls, …) and fmt re-emits any well-formed source in exactly that shape. You’re never required to write canonical form; you just won’t see anything else after fmt.
• The first line may be a #! shebang because # starts a line comment; everything from # to the next \n is whitespace as far as the parser is concerned.
• Inside a string literal, whitespace is literal content. A space or tab between the quotes is part of the string value; an actual newline between the quotes is a literal newline in the value (though the conventional spelling is the \n escape - multi-line literals work but aren’t the canonical form).

Indentation and blank lines never change the meaning of a program; they only change how it reads.

Comments

# line comment - runs to end of line

/* block comment -
   can span multiple lines */

Block comments don’t nest. Because # starts a line comment, the first line of a script may be a Unix shebang and the interpreter will skip it:

#!/usr/bin/env -S jennifer run
use io;
io.printf("hi\n");

(env -S splits the rest of the line into arguments, which is how jennifer run reaches the interpreter on Linux.)

Number literals

Decimal:

42
1_000_000           # `_` is a visual digit separator
3.14
1_000.000_5         # the mantissa side of a float accepts `_` too

Non-decimal integer prefixes:

0xff                # hex
0xDEAD_BEEF
0o755               # octal
0b1010_0110         # binary

All four bases produce ordinary int values - same kind, same operators. The _ separator is allowed between digits but never adjacent to the prefix, adjacent to another _, or at the start / end of the digit run (0x_ff, 1__000, 100_ are all lex errors).

Identifiers

• Variable, method, parameter and library names are letters only: [A-Za-z], up to 64 characters. No digits or underscores.
• Constants are uppercase chunks joined by single _ separators: [A-Z]+(_[A-Z]+)*, up to 64 characters. Every _ must be immediately followed by another uppercase letter. MAX, MAX_RETRIES, HTTP_OK, and A_B_C are all legal; _MAX, MAX_, and MAX__INT are not.
• Variable references use a leading $: define name, refer to it as $name.
• Constant references are bare (no $).
• Method calls are bare and followed by (...).

Types and values

Types

The Default column is the value an uninitialized variable receives (def x as int; produces 0). For compound types the default is an empty container of the declared element / key / value type, not null.

Lists and maps are compound types - they hold other Jennifer values. Nesting works: list of list of int, map of string to list of int, etc. Both are value-typed: $ys = $xs; makes an independent copy, function parameters bind by copy, and const is deep (you cannot mutate the contents of a const list or map).

Note: Jennifer’s list is an array-backed sequence (Go slice underneath), not a Lisp linked list. You get O(1) random access via $xs[i], but no O(1) prepend.

String escape sequences

Both "..." and '...' are valid string delimiters. The following escapes are recognized:

Variables and constants

def name as int init 5;            # declare and initialize
def count as int;                  # declare with the zero value of int (0)
def const MAX as int init 100;     # constant: uppercase name, init required

Uninitialized variables get the default value of their declared type (see the Types table).

init accepts any expression of the declared type, not just literals. Arithmetic, comparisons, function calls, and index reads all work as long as the result kind matches:

def half as float init 5 / 2;                # 2.5 (arithmetic)
def isZero as bool init 1 == 0;              # false (comparison)
def winner as string init decide($a, $b);    # whatever decide() returns
def first as int init $xs[0];                # element read

The same goes for def const NAME - the init expression is evaluated once at declaration time and the result is frozen.

At the def site, names are bare identifiers (no $). The $ sigil is reserved for use-site references that read or assign a variable. So:

def x as int init 5;     # def site - bare name
io.printf($x);              # use site - $ prefix
$x = 42;                 # assignment - $ prefix

def $x as int init 5;    # ERROR: drop the $ here

Constants don’t use $ anywhere (they’re not mutable, so the sigil would have no meaning):

def const MAX as int init 100;
io.printf(MAX);             # use site - bare name
MAX = 200;               # ERROR: cannot assign to constant

Constant names must be UPPERCASE. The full rule is [A-Z]+(_[A-Z]+)*: one or more uppercase chunks joined by single underscores. MAX, MAX_RETRIES, HTTP_OK, and A_B_C are all legal; max, Max, _MAX, MAX_, and MAX__INT are not. The uppercase-only rule is what tells the parser at use sites that a bare identifier is a constant reference, not a variable that forgot its $. Constants also require an init expression - there is no “declare-then-set” form (def const X as int; is rejected).

Assignment uses =:

def x as int init 0;
$x = 42;          # ok
$x = "string";    # error: cannot assign string to int variable

Scoping

• Each {...} block introduces a new scope.
• A binding is visible from its def to the end of the enclosing block, and is inherited by inner blocks.
• Inner scopes can read outer bindings but cannot redefine a name already in scope (no shadowing). The interpreter rejects shadowing at runtime.
• A for loop opens a private scope wrapping init/cond/step/body, so the loop variable does not leak out.
• Constants follow the same scoping rules and reject any later assignment.

Lists and maps

Two compound types let you hold collections of values.

use io;

# A list is an ordered, 0-indexed, mutable sequence.
def xs as list of int init [10, 20, 30];
io.printf("%d\n", $xs[0]);          # 10
$xs[1] = 99;                     # index write
io.printf("%d\n", len($xs));        # 3

# A map is a key->value lookup. Iteration is in insertion order.
def m as map of string to int init {"a": 1, "b": 2};
io.printf("%d\n", $m["a"]);         # 1
$m["c"] = 3;                     # adds new key
$m["a"] = 99;                    # updates existing

# Iterate a list's elements, or a map's keys.
for (def x in $xs) { io.printf("%d ", $x); }      io.printf("\n");
for (def k in $m) { io.printf("%s ", $k); }       io.printf("\n");

A few rules worth knowing up front:

• Out-of-bounds list reads and writes are errors, not silent no-ops. Same for reads of missing map keys - use maps.has($m, key) to test for presence first.
• Lists and maps copy on assignment and on function-call binding. $ys = $xs; makes an independent copy; mutating $ys[0] doesn’t change $xs.
• const is deep. def const NUMS as list of int init [1, 2, 3]; rejects both $NUMS = ... and $NUMS[0] = .... Nested const lists/maps follow the same rule transitively.
• Nesting works: list of list of int, map of string to list of int, and so on. See Nested lists and maps below for the shape rules; best practices has guidance on when nesting gets too deep.
• Empty literals require a declared type: [] and {} are valid literals but the surrounding def x as list of T decides what they hold.

The $xs[] append sugar

For the common “build a list by appending” pattern, $xs[] = item; writes to the position just past the end of the list:

def xs as list of int init [];
$xs[] = 10;
$xs[] = 20;
$xs[] = 30;
# $xs is now [10, 20, 30]

It’s equivalent to $xs = lists.push($xs, item); and produces the same result, but the two are not the same performance-wise (see below); use $xs[] for building a list, lists.push when you want a fresh list and keep the original.

Rules:

• Write-only. $xs[] is only meaningful as a write target. Any read context (io.printf($xs[]), def y init $xs[] + 1) is a parse error.
• Lists and bytes only. $m[] = ...; on a map errors at runtime; maps have no “end-of” position.
• Type-checked. The value is checked against the list’s declared element type, same as $xs[i] = item;.
• const is still deep. $NUMS[] = ...; on a def const list errors with the usual “cannot mutate contents of constant” message.
• Prefer it in hot loops. $xs[] mutates the list in place through the copy-on-write protocol, so appending N items is amortized O(N). lists.push instead returns a new list (values are copy-on-assign), so $xs = lists.push($xs, item) in a loop copies the whole list each pass - O(N^2) overall. For a few appends the difference is invisible; for a per-element build (a raster, a large buffer, a big result set), reach for $xs[]. Reserve lists.push for the “give me a new list, leave the original alone” case.

Nested lists and maps

Compound types nest by repeating the keyword. list of list of int is a list whose elements are themselves lists of ints; map of string to list of int is a map whose values are lists of ints. There’s no depth cap - the parser will recurse as far as you nest.

The “different dimensions, same type” gotcha

Coming from C or Java, you might expect int[3][3] to mean “a 3×3 grid - exactly nine ints, fixed shape”. Jennifer does not work that way.

The declared type only fixes what each level holds, not how many elements are at each level. So all of these are the same list of list of int type:

# 2×2 grid - two rows of two columns
def gridA as list of list of int init [[1, 2], [3, 4]];

# 3×3 grid - three rows of three columns
def gridB as list of list of int init [[0, 0, 0], [0, 0, 0], [0, 0, 0]];

# Jagged - rows have different lengths
def gridC as list of list of int init [[1], [2, 3], [4, 5, 6]];

# Empty - zero rows
def gridD as list of list of int init [];

Same declared type, four very different shapes. At runtime each list just knows its own length; reading $gridA[2] is an out-of-bounds error (only indices 0 and 1 exist), reading $gridC[2][2] works (the third row has three elements), but $gridC[0][2] is out of bounds (the first row has only one element). len($gridC[i]) is the only way to ask “how wide is this particular row?”

If you need a strict shape, enforce it in code:

func makeGrid(size as int) {
    def out as list of list of int init [];
    for (def i as int init 0; $i < $size; $i = $i + 1) {
        def row as list of int init [];
        for (def j as int init 0; $j < $size; $j = $j + 1) {
            $row[] = 0;
        }
        $out[] = $row;
    }
    return $out;
}

When nesting gets deep enough that you’re counting brackets, it’s usually time to reach for a struct or another abstraction - see best practices for the heuristics.

Bytes

bytes is a mutable byte sequence. It looks and acts a lot like a list of int, with two important specialisations:

• Each element is constrained to int in [0, 255]. A write outside that range is a positioned runtime error.
• Indexing returns the byte as an int (you can’t get a one-byte bytes slice via $b[i] - it’s the integer value of the byte).

use io;
use convert;

# Constructing - bytes has no literal form. Either decode a string,
# or start empty and append.
def from_string as bytes init convert.bytesFromString("Hello", "utf-8");
def grown as bytes;
$grown[] = 0x48;
$grown[] = 0x69;

io.printf("from_string: %v\n", $from_string);  # bytes[48 65 6c 6c 6f]
io.printf("grown:       %v\n", $grown);        # bytes[48 69]
io.printf("len:         %d\n", len($from_string));  # 5

# Reading - $b[i] is the byte's value as int.
io.printf("first byte:  %d (= 0x%d|base=16)\n", $from_string[0], $from_string[0]);

# Writing - same int-in-range rule.
$from_string[0] = 0x68;       # lowercase h
io.printf("after edit:  %v\n", $from_string);

# Round-trip back to string.
def s as string init convert.stringFromBytes($from_string, "utf-8");
io.printf("string back: %s\n", $s);

Why bytes is its own type (not just list of int)

The range constraint is the point. A list of int can hold any 64-bit signed integer; bytes can only hold a byte. The runtime enforces this on every write so I/O, hashing, encoding, and crypto code can rely on it. Trying to write $b[i] = 256; is a positioned runtime error, not a silent truncation.

Value semantics, just like lists and maps

def src as bytes init convert.bytesFromString("Hi", "utf-8");
def dst as bytes init $src;
$dst[0] = 0x78;            # mutates only dst
# $src is still bytes[48 69]

Function parameters bind by copy too, so a func mutate(b as bytes) that writes into $b doesn’t leak back to its caller. const is deep: def const B as bytes init ...; rejects both $B = ... and $B[i] = ....

The $b[] = byte; append form

Bytes share the append sugar with lists:

def buf as bytes;
$buf[] = 0x48;
$buf[] = 0x69;
# buf is now bytes[48 69]

The byte you append must be an int in [0, 255].

Codecs and rune vs byte counts

• convert.bytesFromString(s, codec) and convert.stringFromBytes(b, codec) are the canonical bridges. These two handle "utf-8" only; every other character encoding lives in the encoding library.
• stringFromBytes is strict at boundaries: invalid UTF-8 input is a runtime error, not a silent replacement character.
• len($b) returns the byte count; len($s) on a string returns the rune count. They will disagree for any non-ASCII input.
• io.readBytes(n) -> bytes reads n bytes from stdin; io.readChars(n) -> string reads n Unicode code points (1-4 bytes each, decoded from UTF-8). See libraries/io.md for details.

Structs

A struct names a fixed set of typed fields. Use a struct whenever a multi-value bundle would otherwise be a map keyed by string literals - the fields are checked at construction time, the field names are part of the type, and reading $p.x is faster and clearer than indexing a map by "x".

A struct is defined once at the top level and reused everywhere:

def struct Point { x as int, y as int };
def struct Line { from as Point, to as Point };

The shape is def struct Name { field as type, field as type, ... };. The struct name follows the identifier rule (letters only, up to 64 characters); field names follow the same rule. The trailing ; is required (every statement ends in one).

Constructing, reading, writing

# Construct - every field must be named at the literal.
def p as Point init Point{ x: 3, y: 4 };

# Read.
io.printf("%d %d\n", $p.x, $p.y);    # 3 4

# Write.
$p.x = 30;

The struct literal Point{ x: 3, y: 4 } requires every field; a missing field is a positioned error, and so is an unknown one (z: 5 on a Point). Field order in the literal is free - the runtime stores each field at its declaration position regardless.

def p as Point; (no init) gives every field its declared zero, recursing through nested struct fields. So def L as Line; produces Line{from: Point{x: 0, y: 0}, to: Point{x: 0, y: 0}} without any extra ceremony.

Nested structs and chained access

A struct’s field can itself be a struct, a list, a map, or any combination. Reads and writes chain through .field and [index] in whatever order makes sense:

def L as Line init Line{ from: Point{ x: 0, y: 0 }, to: Point{ x: 10, y: 20 } };

io.printf("%d\n", $L.to.x);    # 10  - field after field

$L.from.x = 5;                  # write through the chain

A struct field that’s a list works the same way: $bag.items[0] = 99; descends through the .items field and writes into the list at index 0.

Value semantics

Like lists, maps, and bytes, structs are value-typed:

def p as Point init Point{ x: 1, y: 2 };
def q as Point init $p;     # independent copy
$q.y = 99;
# $p is still Point{x: 1, y: 2}; $q is Point{x: 1, y: 99}.

Function parameter binding copies too, so func translate(pt as Point, dx as int) that writes into $pt doesn’t leak back to the caller.

const is deep

def const ORIGIN as Point init Point{ x: 0, y: 0 }; rejects both $ORIGIN = ... (rebinding) and $ORIGIN.x = ... (content mutation), including writes that descend through nested struct fields. Same rule as lists and maps - the value behind a const is frozen at every depth.

Strict at boundaries

• Unknown struct type at declaration: def x as Widget; when no def struct Widget exists is a positioned runtime error (“unknown struct type”).
• Missing or unknown field at the literal: positioned errors that point at the offending position.
• Field type mismatch on write: $p.x = "hi"; on x as int errors with the declared type and the actual value’s kind.
• Field access on a non-struct value: $xs.foo where $xs is a list errors with “field access .foo requires a struct, got list”.

Methods

func greet(name as string) {
    io.printf("hello, %s\n", $name);
}

greet("Jennifer");   # call it from top level

Two keywords, two jobs:

• def [const] NAME ... introduces a binding (variable or constant).
• func NAME(p as TYPE, q as TYPE) { ... } introduces a method.

Parameters use bare identifiers (same rule as def) and each has a declared type. Inside the body, parameters are referenced as $p like any other variable. At the call site, the interpreter checks the number of arguments and the kind of each one - mismatches produce a positioned error.

Return values use return EXPR; to return a value or return; to return null. A body that runs to the end without return also yields null. Methods don’t declare a return type; the caller’s type check (e.g. def x as int init mymethod();) is what enforces the value’s kind at the use site.

Recursion works out of the box - methods are hoisted, so any method can call any other (or itself) by name.

func fact(n as int) {
    if ($n == 0) { return 1; }
    return $n * fact($n - 1);
}

io.printf("%d\n", fact(5));    # 120

Methods are hoisted: all func NAME() { ... } declarations are collected before any top-level statement runs, so a method can be called from anywhere in the file regardless of where it’s defined. There is no required entry point - top-level statements execute in source order.

Methods can only be defined at the top level (not inside another method’s body). Method bodies inherit the global scope, so top-level variables are visible inside methods (subject to the no-shadowing rule).

Methods cannot shadow imported builtins. If you write use io; and then func io.printf() { ... }, the program is rejected:

runtime error at 2:1: method "printf" shadows a builtin from `io`;
rename it or remove `use io;`

Without the use io;, the name is yours to define. This is the same no-shadowing discipline Jennifer applies to variables.

Control flow

Operators

Division has two operators. / always returns a float (Python 3 style). // returns the floor, keeping the type when both operands are ints:

5 / 2          # 2.5 (float)
5 // 2         # 2   (int)
5.0 / 2.0      # 2.5 (float)
5.7 // 2.0     # 2.0 (float - floor of a float division)

So def x as int init 5 / 2; is rejected (right side is float). Use 5 // 2 for an int result, or def x as float init 5 / 2;.

(Line comments are #, freeing // for the Python-3 floor-division operator. The # choice also lets Jennifer files start with a shebang: #!/usr/bin/env -S jennifer run.)

Precedence (low to high): or, and, not, comparison, bitwise |, bitwise ^, bitwise &, shifts << >>, additive (+, -), multiplicative (*, /, //, %), unary - / ~. Use parentheses to override: (1 + 2) * 3. The bit-op rungs sit between comparison and additive following Python’s precedence, so $x & 0xff == 0 parses as ($x & 0xff) == 0 (the intuitive interpretation), not the C/Go shape $x & (0xff == 0). Examples that follow the rules:

not 1 == 2                  # not (1 == 2) -> true
1 > 0 and 2 > 1             # true
true or false and false     # true or (false and false) -> true
-3 + 10                     # (-3) + 10 -> 7
-3 * 2                      # (-3) * 2 -> -6

and and or short-circuit. The right operand is only evaluated when the left doesn’t already decide the result. That matters when the right side has side effects:

def gate as bool init false;
def result as bool init $gate and expensive();   # expensive() not called

Mixed int/float arithmetic promotes the int to float and the result is a float (3 + 0.5 -> 3.5). / always returns float, even with two int operands (5 / 2 is 2.5, not 2). Use // when you want an integer quotient: 5 // 2 is 2. This is Python-3 division, not C/Java division.

Bitwise operators

The bit operators take int operands only - float is rejected with a positioned error. The shifts are arithmetic (sign-extending >>); a negative shift count is rejected, and a count >= 64 saturates to 0 or -1 the way hardware does. Non-decimal literals (0xff, 0o755, 0b1010_0110) and the _ digit separator (1_000_000, 0xDEAD_BEEF) make bit-twiddling code much easier to read.

def mask as int init 0xff;
def x as int init 0xDEAD_BEEF;

io.printf("low byte:  %d|base=16\n", $x & $mask);   # ef
io.printf("flip last: %d|base=16\n", $x ^ 1);       # dead_beee
io.printf("shift 4:   %d|base=16\n", $x >> 4);      # dead_beef >> 4

Conditionals and loops

if ($n == 0) {
    io.printf("zero");
} elseif ($n < 10) {
    io.printf("small");
} else {
    io.printf("large");
}

while ($i < 5) {
    $i = $i + 1;
}

for (def i as int init 0; $i < 10; $i = $i + 1) {
    io.printf($i);
}

# for-each over a list or map.
for (def x in $xs) {
    io.printf("%d ", $x);
}
for (def k in $m) {
    io.printf("%s=%d ", $k, $m[$k]);
}

Conditions in if, elseif, while, and for must be bool - there is no implicit truthiness. Use a comparison ($x == 0) to get a bool. For-each (for (def x in $coll)) doesn’t take a condition - it walks the whole collection.

Loop variable scope

C-style for opens its own scope. Where you def the iterator variable decides whether you can still see it after the loop.

# Loop-local: declare inside the for-init. The iterator lives only for
# the duration of the loop.
for (def i as int init 0; $i < 10; $i = $i + 1) {
    io.printf("%d\n", $i);
}
io.printf("%d\n", $i);   # ERROR: `i` not in scope here

# Outer-scope: declare in the surrounding scope, assign in the for-init.
# The variable survives past the loop and holds the value that made the
# condition false (10 here).
def i as int;
for ($i = 0; $i < 10; $i = $i + 1) {
    io.printf("%d\n", $i);
}
io.printf("%d\n", $i);   # ok - prints 10

The loop-local form is the recommended style; reach for the outer-scope form only when you actually need to inspect the iterator after the loop ends. For-each (for (def x in $coll)) is always loop-local - the iteration variable lives in a fresh scope each pass through the loop and is gone once the loop exits.

repeat ... until (post-test loop)

For loops that should run at least once, then keep going until a condition becomes true:

def n as int init 0;
repeat {
    io.printf("n=%d\n", $n);
    $n = $n + 1;
} until ($n >= 3);
# prints n=0, n=1, n=2 - the body runs three times before until is true.

The body runs unconditionally on entry, then until (cond) is checked after each iteration. The loop stops when cond evaluates true.

This is the post-test counterpart to while. The keyword pair repeat/until was chosen over do { } while ... so the condition inversion (“loop until done”) reads as English and matches the rest of Jennifer’s word-operator style (and, or, not). Like every other condition slot, cond must be bool.

break and continue

break; exits the innermost enclosing loop:

for (def i as int init 0; $i < 10; $i = $i + 1) {
    if ($i == 5) { break; }
    io.printf("%d ", $i);
}
# prints "0 1 2 3 4 "

continue; skips the rest of the current iteration and starts the next one. In a C-style for loop, the step expression ($i = $i + 1) still runs before the condition is re-checked - matching the behaviour in C, Go, Java, and Python:

for (def i as int init 0; $i < 5; $i = $i + 1) {
    if ($i % 2 == 0) { continue; }
    io.printf("%d ", $i);
}
# prints "1 3 "

Both work in while, C-style for, for-each (for (def x in $coll)), and repeat ... until. In repeat, continue jumps to the until check (skipping the rest of the body); the loop still terminates normally when until becomes true.

Misuse:

• break and continue only exist inside a loop. Using one at the top level or as a stray statement in a method body that has no enclosing loop is a positioned runtime error.
• They do not cross the method-call boundary. A break inside a method body looks for a loop in that method, not in the caller. If the called method has no loop, the break errors.
• They only catch the innermost loop. To exit several levels at once, use a flag variable that the outer loop checks, or refactor the inner work into a method that returns when done.

exit

exit; terminates the whole program immediately - it skips the rest of the current method, every caller frame, and every remaining top-level statement. The bare form yields exit code 0:

use io;
io.printf("ok\n");
exit;                   # process ends with code 0
io.printf("never\n");   # not reached

exit EXPR; sets the exit code; EXPR must evaluate to int:

use io;
io.printf("error: input missing\n");
exit 2;                 # process ends with code 2

exit is distinct from return. return ends the current method’s body and yields a value to the caller; exit ends the program. Use return when a method has done its job; use exit when the whole run is over.

try, catch, throw

Catchable errors. throw EXPR; signals an error from any reachable point; try { body } catch (NAME) { handler } runs the body and, if anything inside it throws (user code or a runtime failure like out-of-bounds), runs the handler with NAME bound to the thrown value:

use io;

try {
    def n as int init convert.toInt($input);
    process($n);
} catch (err) {
    io.printf("not a number: %s\n", $err.message);
}

What can be thrown

Any value. The convention is an Error struct - the runtime auto-defines that struct shape so user code can rely on it without a def struct Error { ... }; of its own:

def struct Error {
    kind    as string,    # short symbolic tag
    message as string,    # human-readable
    file    as string,
    line    as int,
    col     as int,
};

User code throws an Error{...} to signal expected failure modes; catch sites dispatch on $err.kind:

func parseConfig(src as string) {
    if (not strings.contains($src, "=")) {
        throw Error{
            kind: "parse_error",
            message: "missing `=`",
            file: "", line: 0, col: 0
        };
    }
    # ... happy path ...
}

try {
    parseConfig($cfg);
} catch (err) {
    if ($err.kind == "parse_error") {
        io.printf("config invalid: %s\n", $err.message);
    } else {
        throw $err;     # not our concern; let it propagate
    }
}

A bare throw "boom"; still works (any value); the catch handler just won’t be able to read .kind / .message off it. Use convert.typeOf($err) if you need to branch on the kind.

What can be caught

• User-issued throw EXPR; - whatever the user passed, copied into the catch binding (value semantics, like every other binding boundary).
• Runtime errors - out-of-bounds reads / writes, missing map keys, type mismatches, division by zero, undefined names, bytes-element range violations, and the rest of the positioned runtime errors. The runtime wraps them into the canonical Error struct with kind = "runtime" (more specific tags will land per site over time) and the original file / line / col preserved.

What can NOT be caught

• exit / exit EXPR; - the program-level escape hatch stays escape. try { exit 1; } catch (e) { ... } lets the exit through; the catch block does not run.
• return / break / continue - they’re control flow, not errors. try { break; } catch (e) { ... } breaks the enclosing loop; the handler does not run.

Re-throwing

throw $err; inside a catch re-raises - the value propagates past the current try/catch to the next enclosing try. Same value unless replaced.

No finally in v1

Jennifer does not have a finally clause yet. The pattern is “do the cleanup explicitly in both branches” until a real cleanup need surfaces (probably with file handles in a future fs library).

Concurrency

Jennifer’s concurrency surface is small on purpose. A program can launch a computation in the background with spawn, get back a handle of type task of T, and read the result later with the task library.

use io;
use task;

def t as task of int init spawn { return slowComputation(); };
# ... other work happens here, in parallel with the spawn body ...
def n as int init task.wait($t);
io.printf("answer: %d\n", $n);

That’s the whole story. No channels, no shared memory, no locks, no cancellation tokens, no goroutine-leak gotchas. The four pieces

• the spawn keyword, the task of T type, the task library, and the exit-time loud-fail contract - are what concurrency ships.

The model

A spawn { ... } block evaluates its body concurrently with the rest of the program. It returns immediately with a task of T, where T is the body’s declared return type at the use site. The body runs to its own return EXPR;; that becomes the task’s result. When the body raises a runtime error instead, that becomes the task’s error.

Reading the result is a separate, explicit step:

See the task library reference for the full surface and worked examples per builtin.

Why value-semantics capture matters

The biggest single design choice is that a spawn block captures its surrounding scope by deep copy, not by reference. Variables visible at the spawn site are copied into the spawn frame at the moment of launch; mutations on either side afterwards are independent.

use io;
use task;

def xs as list of int init [1, 2, 3];
def t as task of int init spawn {
    return $xs[0] + $xs[1] + $xs[2];   # sees [1, 2, 3]
};

$xs[] = 99;                            # parent mutates after spawn

def total as int init task.wait($t);   # still 6
io.printf("%d\n", $total);

This is the same value-semantics discipline Jennifer applies everywhere - lists, maps, structs, bytes all copy on assignment and on function-parameter binding. Concurrency reuses the rule, so data races are impossible by construction. There is no shared mutable state to race on.

The cost is the obvious one: deep-copying a large structure into a spawn frame is O(N). For a 10 000-element list that’s measurable. The benefit is that you never need a lock, a mutex, an atomic, or a channel to coordinate; concurrent code reads like sequential code with spawn markers.

Patterns

Parallel compute

use io;
use task;

func work(n as int) {
    # ... CPU-bound computation ...
    return $n * $n;
}

def tasks as list of task of int init [];
def i as int init 1;
while ($i <= 4) {
    $tasks[] = spawn { return work($i); };
    $i = $i + 1;
}

def results as list of int init task.waitAll($tasks);
# results are in list order, regardless of completion order
io.printf("%a\n", $results);

task.waitAll returns results in the same order as the input tasks, not the order in which they completed. That’s the property most parallel-compute code wants.

Fire and forget

For background work whose result you genuinely don’t care about, launch with spawn and mark the handle with task.discard:

use task;

def alive as task of null init spawn {
    # ... log a metric, send a notification, prefetch a cache ...
    return null;
};
task.discard($alive);

task.discard is required even for happy-path background work because of the loud-fail contract (next section). It declares to the runtime that no result is expected, so a later failure won’t crash the program.

First-to-finish

task.waitAny returns the index of whichever task finished first; the caller follows up with task.wait($ts[$idx]) to read its value. The other tasks keep running and need explicit observation:

use io;
use task;

def fast as task of int init spawn { return 1; };
def slow as task of int init spawn { return 2; };
def candidates as list of task of int init [$fast, $slow];

def winner as int init task.waitAny($candidates);
def value as int init task.wait($candidates[$winner]);
task.discard($candidates[1 - $winner]);

io.printf("winner=%d val=%d\n", $winner, $value);

The loud-fail contract

If a spawn body raises a runtime error and the program never observes the resulting task (never task.waits it, never task.waitAlls it, never task.discards it), Jennifer prints the error to stderr at program exit and exits non-zero.

This is deliberate. The default of every other concurrency model is some flavour of “errors in spawned work get silently dropped unless you go out of your way to handle them.” That’s a footgun

• bugs hide inside unobserved tasks until something else breaks much later. Jennifer’s contract is the inverse: an unobserved spawn error is always loud. The only way to silence it is to say so explicitly with task.discard.

use task;

def bad as task of int init spawn {
    def xs as list of int init [];
    return $xs[5];                          # error inside the body
};
# the program ends here without touching $bad

$ jennifer run example.j
spawn error (unwaited): list index 5 out of bounds (len 0)
$ echo $?
1

Three ways to make a spawn quiet:

1. task.wait($t) - read the result. The error rethrows at the wait site; an enclosing try/catch can suppress it.
2. task.waitAll($ts) / task.waitAny($ts) - same idea, with waitAll observing every survivor on the way out.
3. task.discard($t) - the explicit fire-and-forget marker.

Doing nothing is not a fourth option.

Beware infinite spawns. The loud-fail scan blocks on every unobserved task to determine whether it produced an error. spawn { while (true) { ... } } without task.discard will hang the program at exit, since the goroutine never finishes. Long-running or potentially-non-terminating spawns should be paired with an explicit task.discard at the top of the scope.

What’s deliberately not in v1

The current surface stops short of several features common to other languages’ concurrency stories. Each was considered and deferred, not rejected:

• Channels. Inter-task communication beyond “wait for a return value” is not in v1. The chosen surface (task of T + wait/waitAll/waitAny) handles the most common cases without the bookkeeping channels require. A channel primitive would arrive in a later milestone.
• Cancellation tokens. No way to signal a running task to stop. The spawn body runs to completion or to an unhandled error. Cancellation is an open design question (cooperative flag? hard abort? structured-concurrency tree?) and stays deferred.
• Timeouts. No built-in task.waitWithTimeout. Build one with a sentinel spawn that returns after time.sleep and a task.waitAny over the pair. A higher-level helper may ship later.
• Structured concurrency. No automatic scope-bounded termination of unwaited tasks. The loud-fail contract is Jennifer’s lighter-weight answer: not as strong a guarantee as Trio / async-await scopes, but enough to keep spawned errors visible.
• Parallel for / map. No for parallel (...) syntax. If you need it, write the explicit spawn / waitAll pair; that’s what a parallel-map combinator would compile to anyway.
• Atomics, mutexes, shared mutable state. Value-semantics capture removes the need.

The single most likely follow-on in this area is a time-aware helper for timeouts; channels are second; structured-concurrency scopes a distant third (and might never land, since the loud-fail contract already addresses the main pain point).

See also

• task library reference - the five builtins, error propagation, worked examples.
• Control flow - try/catch works the same way around task.wait as around any other runtime error.
• Methods - calling methods from inside a spawn body works normally; the body inherits the global env the same way any other call frame does.
• docs/milestones.md - the concurrency entry has the design rationale (data-race-freedom by construction, the loud-fail decision, what’s deferred to later).

Imports

Three keywords, three mechanisms:

use io;                   # library import - enables `io.printf`, `io.sprintf`, ...
include "helpers.j";      # textual file splice - pastes helpers.j here
import "./config.j";      # module import - loads config.j as its own module

use and include operate at the textual level; import is the module system - a real module boundary with run-once initialisation. A module loads and initialises before the code that imports it (see Module imports below).

Library imports

use NAME; enables a built-in library. Every library is namespaced - every name lives behind the library’s prefix (io.printf, math.sqrt, convert.toInt). Nothing auto-loads; every program states its imports. Each library has its own reference doc; the table below is the index.

len(EXPR) is a language built-in (not a library) - polymorphic over string / list / map / bytes; no import needed.

See libraries/index.md for a fuller catalog and the library-organization principles, or libraries/cheatsheet.md for an alphabetical lookup of every builtin function and constant.

Quick orientation - if you’re reading top to bottom and just want a flavor:

use io;
use convert;
use math;

io.printf("%s\n", convert.typeOf(5 / 2));     # "float"   [convert]
io.printf("%d\n", math.floor(math.PI * 2.0)); # 6         [math + io]
io.printf("%s\n", convert.toString(true));      # "true"    [convert]

The per-library docs cover every function in detail along with error cases.

Namespaced calls and aliasing

A qualified call is always prefix.name(...); a qualified constant is prefix.NAME. No spaces around the dot. The prefix is the library name by default; an as ALIAS clause renames it at the use site:

use os;
use math as m;

io.printf("on %s\n", os.platform());      # canonical prefix
io.printf("pi=%f\n", m.PI);               # aliased prefix

Aliasing rules

• Rename, not addition. After use os as o; only o. resolves; os.platform() errors with a “did you mean o?” hint. Matches Python’s import foo as bar shadowing of foo.
• Canonical name freed. The aliased canonical name (os above) is freed for ordinary identifier use - you could write func os() { ... } after use os as o;. The style guide recommends against it - it reads as a library call at first glance and surprises the reader.
• Without aliasing, the prefix is reserved. Bare use os; reserves os as a namespace prefix for the rest of the program; func os() {} then errors with shadows imported namespace 'os'.
• Repeating a use is a silent no-op in the REPL. In a batch program a duplicate use is accepted as a no-op too. Pick one form per program.
• Module import works in the REPL. import "./mod.j"; at the prompt loads the module and binds its namespace (local ./ / ../ paths resolve against the current directory; a bare name walks the system module path), so a later mod.member resolves across inputs. Re-typing the same import is a no-op. A module is loaded once and cached by path, so editing the file and re-importing in the same session keeps the cached version - restart the REPL to pick up edits.

len is a language built-in

len(EXPR) is not a library function - it’s a reserved keyword and a language primary expression. Polymorphic over string / list / map / bytes; no use statement needed:

def n as int init len("hello");        # 5 (rune count)
def m as int init len([1, 2, 3]);      # 3 (element count)

len used to live in an auto-loaded core library; use core; now errors with a migration hint. Build-version constants moved from core to meta (use meta; then meta.VERSION, meta.BUILD).

File splices (include)

include "PATH.j"; textually splices another .j source file at the point of include. The path is a string literal that must end in .j. Relative paths resolve from the directory of the file containing the include; absolute paths and subdirectories work:

include "helpers.j";          # sibling file
include "subdir/utils.j";     # subdirectory
include "../shared/util.j";   # parent dir
include "/abs/path/lib.j";    # absolute path

File splices may appear anywhere a statement is allowed, including inside a block:

use io;
include "helpers.j";          # ← spliced here; whatever helpers.j contains lands here
io.printf($helperValue);

Circular includes (file A includes file B, B includes A) are detected and rejected with an error.

Module imports

import "PATH.j" [as NAME]; loads another .j file as a module - a real boundary, not a textual splice. Where an include pastes tokens into the current scope, an import runs the referenced file as its own program: its top level executes once, in its own scope, before the importing file’s body runs.

use io;
import "./config.j";   # config.j initialises before this line returns
import "./db.j";       # db.j (which may itself import config.j) initialises next

io.printf("app: running\n");

The path decides where the module is found by its leading token:

• Local - import "./util.j"; or import "../shared.j"; resolves relative to the importing file’s directory.
• Absolute - import "/opt/pkg/m.j"; (leading /) is an absolute filesystem path.
• Module - import "util.j"; (no ./, no /) is looked up on the module search path: the system module directory first, then each -I DIR passed on the command line. The importing file’s own directory is not consulted for this form. A / anywhere but the front is an ordinary subdirectory (import "sub/util.j"; works in every form).

Guarantees:

• Run-once. A module’s top level runs exactly once per program, cached by its resolved absolute path. Importing it again returns the same initialised module without re-running it.
• Post-order init. Imports initialise depth-first: a module is fully initialised before any module that imports it. If main imports db and db imports config, the order is config, then db, then main’s body.
• Acyclic. An import cycle (a imports b imports a) is a load-time error that names every edge in the loop.
• Load errors are not catchable. A parse error or a throw during a module’s initialisation fails the program at load. An import is a declaration, not an expression, so it cannot appear inside a try/catch - wrapping one is itself a parse error.

A module publishes with export; unmarked names are private. Put export in front of a top-level def const, def struct, or func to make it reachable through the importer’s alias. A forgotten export stays internal (the safe default) - reaching a private name from outside is a positioned “not exported from module” error. (export is meaningful only in a module: it is a parse error in a jennifer run script.)

# config.j
use convert;
export def const MAXCONN as int init 16;   # public
def const NAME as string init "jdb";        # private (no export)
export func describe() {                     # public
    return NAME + " x" + convert.toString(MAXCONN);
}

Reaching a module’s surface:

• alias.fn(args) calls an exported function - the arguments are evaluated in your code, but the body runs in the module’s own scope (its constants and other functions, plus whatever it imported - use is not transitive, so the module’s use net; does not give you net.*).
• alias.CONST reads an exported constant.
• alias.Struct names an exported struct type, and alias.Struct{...} builds one. A module struct keeps its identity (module, name) across the boundary, so you can hold one (def p as alias.Struct init alias.make();), read its fields, and pass it back - while a.Point and b.Point from two modules stay distinct types. An exported struct or function signature may not expose a private struct (a referential-closure error at the export).
• A module top level is declarations-only: def const, def struct, func, use, import - no mutable def and no free-standing statements. A def const initializer may still call a private func.

use io;
import "./config.j" as config;

io.printf("%s\n", config.describe());   # calls an exported function
io.printf("%d\n", config.MAXCONN);      # reads an exported constant

Testing: a co-located MODULE_test.j is a white-box overlay - jennifer test MODULE_test.j splices MODULE.j in first, so its test* methods reach the module’s private names by bare identifier. For black-box tests, import the module and exercise its exported surface. See the runnable examples/modules/ chain.

include vs import

Both read another .j file, but they differ at the boundary:

• include does a textual splice with no module boundary - the spliced file’s top-level names land directly in the enclosing program’s scope, and the same file spliced twice contributes its definitions twice. Use it to share snippets within one program.
• import loads a module - separate scope, run-once, post-order init. Use it to compose independent files.

Mixing the keywords up produces a positioned, actionable error:

include io;     → error: `include` is for files; use `use io;` for
                  system libraries
use foo.j;      → error: `use` is for system libraries; for files use
                  `include "foo.j";`
include foo.j;  → error: file splices take a string literal:
                  `include "foo.j";`
include "foo.go"; → error: include path "foo.go" must end with `.j`
import foo;     → error: `import` takes a quoted module path
                  (`import "foo.j";`); for a system library use `use foo;`

Notes:

• The included file’s contents must be valid where the include appears. A file containing a top-level def cannot be included inside a block (since definitions are only allowed at the top level).

Jennifer style guide

This is the recommended source style for Jennifer programs. jennifer fmt re-emits source in exactly this shape, so anything you write that matches the spec will survive a fmt round-trip unchanged.

The guide is short on purpose: there are only a handful of rules, but they are consistent. If you’ve used gofmt, prettier, rustfmt, or PSR-12, nothing here will surprise you.

Spacing

• One space around every binary operator: $i = 1 + 2;, not $i=1+2;. Applies to + - * / // % < > <= >= == and or and =.
• Unary - hugs its operand: -5, -$x, -fact($n - 1). No space between the - and the value it negates.
• Word-form unary operators take a space: not $ok, never not$ok. Same goes for any other keyword operator the language grows.
• One space after , and ; inside for (...; ...; ...), never before. for (def i as int init 0; $i < 10; $i = $i + 1).
• No space inside parentheses: io.printf("hi"), not io.printf( "hi" ).
• One space between a keyword and its (: if (cond), while (cond), for (...). Function calls don’t get this space: io.printf(...).
• No space inside [ ] or { } list/map literals: [1, 2, 3], {"a": 1, "b": 2}, not [ 1, 2, 3 ] or { "a" : 1 }. Empty literals are [] and {}. Same rule as ().
• No space before [: $xs[0], not $xs [0]. Index expressions hug their target.
• No space inside [] for the append form: $xs[] = item;, never $xs[ ] = item; or $xs [ ] = item;. Same rule as $xs[0] hugs its target and its brackets.
• One space after : in map literals, never before: {"a": 1}, not {"a" :1} or {"a":1}.
• No trailing whitespace on any line.

Indentation

• 4 spaces per level, no tabs. Re-indenting on } always lands you back on a multiple of 4.
• One level per block - method body, if/elseif/else body, while body, for body.

Braces

• 1TBS (one true brace style): opening brace on the same line for everything - methods and control flow alike - separated by one space: func fact(n as int) {, if ($x > 0) {, else {. (Jennifer uses the uniformly-same-line variant that Java, Go, Rust, and the Linux kernel also use.)

• } on its own line, except for the } else { / } elseif (...) { cascade, where else/elseif continues on the same line as the preceding }.

• fmt always expands blocks across multiple lines - the canonical form has the opening brace at end-of-line, each body statement on its own indented line, and the closing brace on its own line. Applies uniformly to method bodies, control-flow blocks (if / elseif / else, while, for, repeat), try { } catch (e) { }, and spawn { } block expressions. Single-line blocks are still legal source (the parser accepts them), but fmt rewrites them to the expanded form for consistency.

• Struct declarations expand to one field per line. def struct Point { x as int, y as int }; reflows to

  def struct Point {
      x as int,
      y as int
  };
  

  Struct literals (Point{x: 1, y: 2}) stay inline - they read like map literals and the two form styles match.

• Tail keywords cuddle the preceding }. } else { ... }, } elseif (cond) { ... }, } catch (e) { ... }, and } until (cond); all keep the trailing keyword on the same line as the closing brace. }; (a struct-decl terminator) also cuddles.

Line length

• Soft limit: 100 columns. fmt doesn’t hard-wrap arbitrary code (that would risk changing meaning), but it will break at the binary joiners +, and, and or when a line has already grown past 100 columns. The break lands after the joiner - the operator hangs at end-of-line and the continuation is indented one level deeper:

  def body as string init "line one\r\n" +
      "line two\r\n" +
      "line three\r\n";
  

  Source-level line breaks at these joiners are also preserved even when the line would fit under 100 - so the shape above survives a fmt round-trip byte-for-byte. Long argument lists, deeply nested calls, and everything else stay on one line unless you break them by hand; fmt isn’t going to guess where.

Statements

• Every statement ends with ; - no exceptions, including the last statement in a block.
• One statement per line. Don’t chain multiple statements with ; on a single line.
• Blank lines separate logical groups - imports from method definitions, methods from top-level code, distinct steps within a long block. Never more than one consecutive blank line.

Loops

• Declare the iterator variable inside the for init, not in the surrounding scope. The variable’s lifetime should match the loop’s:

  for (def i as int init 0; $i < 10; $i = $i + 1) {   # preferred
      io.printf("%d\n", $i);
  }
  

  not

  def i as int;
  for ($i = 0; $i < 10; $i = $i + 1) {                # avoid
      io.printf("%d\n", $i);
  }
  

  The loop-local form is self-contained (reading the for line tells you everything about i), keeps the iterator out of the surrounding scope, and matches the for-each shape (for (def x in $coll)) which is always loop-local. The outer-scope form is only justified when you genuinely need the iterator’s value after the loop ends - for example, to report which iteration triggered a break in a future language version that adds break. Use it deliberately, not by habit.

• One concern per loop. If the body is more than a screen, consider whether the work belongs in a helper method called from inside the loop.

Names

• Variables, methods, parameters: lowercase or camelCase if the name has multiple words. Identifiers are [A-Za-z]{1,64} - no digits, no underscores.
• Constants: UPPERCASE, with _ as a single word separator. The full rule is [A-Z]+(_[A-Z]+)*, up to 64 characters: one or more uppercase chunks joined by single _. Every _ must be immediately followed by [A-Z] - no leading, trailing, or consecutive _. Examples: MAX, MAX_RETRIES, HTTP_OK, A_B_C. Digits and lowercase letters are not allowed.
• Library names: lowercase, single word where possible (io, math, strings, meta).

Namespaced calls

Domain libraries are addressed by prefix.name(...). The dot binds tight on both sides, like a method call’s (:

• No space around .: os.platform(), never os . platform().
• The call parens still hug the callee: os.platform(), not os.platform ().
• use lib as alias; is one space on each side of as: use bio as b;, never use bio as b;.

When you alias a library, the canonical name is freed for ordinary identifier use (e.g. you could write func os() { ... } after use os as o;). Don’t. Reusing a library’s canonical name reads as “this is a call into the library” at first glance, then surprises the reader when it isn’t - keep the canonical name out of the user-method pool even when aliasing has technically freed it.

Strings

• Prefer double quotes: "hello" over 'hello'. Both forms parse escape sequences the same way, but mixing styles in one file reads as noise. Use single quotes only when the string contains a " you’d otherwise need to escape.
• Escape sequences are explicit: "\n", "\t", "\\". Don’t rely on multi-line string literals - Jennifer doesn’t have them.

Comments

• # line comment for short notes that belong on or just above the thing they describe. The very first line may be a shebang (#!/usr/bin/env -S jennifer run); the lexer treats it as a comment.
• /* block comment */ for longer commentary that doesn’t fit one line. Block comments nest, so wrapping a chunk of code that already contains a block comment in another /* ... */ works.
• Inline block comments inside (, [, or after . get a space on the operand side. printf(/* note */ $x), not printf(/* note */$x). This is a deliberate exception to the “no space inside ()” rule above: */$x runs together visually and is harder to read than the spaced form. The comment hugs the opening delimiter (no space between ( and /*) so only the operand side picks up the space. Same rule for [/* note */ 0] and $obj./* doc */ field.
• Comments explain why, not what. The code already says what.

Doc comments

Document every public func, def struct, and def const with a doc comment, and open a file with a module preamble. A doc comment is a block comment that opens with exactly /** (a plain /* stays an ordinary comment), sits immediately above the construct it documents, and holds a summary line, an optional description, and @-tags. This is the format the docblock module parses, so your docs are machine-readable, not just prose.

/**
 * Distance between two points.
 * A longer description can follow the summary line.
 * @param ax {float} first x coordinate
 * @param ay {float} first y coordinate
 * @return {float} the Euclidean distance
 * @since 0.9
 */
export func distance(ax as float, ay as float, bx as float, by as float) { ... }

• Types go in { }, in Jennifer’s own syntax: {int}, {list of int}, {map of string to int}, {json.Value}. There is no any - an opaque value documents as json.Value or a named struct.
• export is read from the keyword, never a tag - don’t write @public.
• Tags: @param name {type} desc (functions) and @field name {type} desc (structs), one per parameter / field; @return {type} desc; @throws {type} desc; and the universals @since, @deprecated [reason], @see, @example, @internal.
• A file preamble is a doc comment carrying @module name, plus optional @author, @version, @license. It goes at the top, after the SPDX header.
• Keep doc names in step with the code. docblock cross-checks @param / @field names against the real declaration and reports drift, so a stale doc is a caught bug, not a silent one.

jennifer fmt preserves doc comments and keeps each on its own line above its construct, so a formatted file is exactly what docblock expects to parse.

Source file conventions

• .j extension for all Jennifer source. The interpreter rejects anything else.
• One SPDX header at the top of every committed .j file (the project uses LGPL-3.0-only - see existing examples).
• use and import statements come first, before any methods or top-level statements. Group use lines together, then import lines, then a blank line, then the rest of the program.
• Blank line after a leading comment block. If the file opens with a header comment (SPDX line, copyright, file description, shebang), leave one blank line between the comment block and the first code line. Files that start directly with code (no header) start on line 1 - no leading blank.
• Trailing newline at end of file.

Editor configuration

Drop the following into a .editorconfig file at your project root and any editor with EditorConfig support will enforce the spacing and file-encoding rules above automatically:

# .editorconfig
root = true

[*.j]
indent_style = space
indent_size = 4
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

That covers the indentation rule (4 spaces, no tabs), trailing-whitespace and final-newline conventions, and pins UTF-8 + LF line endings so collaborators on different OSes don’t accidentally introduce CRLF diffs. jennifer fmt re-emits source in the same shape, so the EditorConfig settings and the formatter never disagree.

If you keep .j files alongside other languages in one repository, add a generic fallback as the first block so plain text files don’t drift either:

[*]
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

A complete example

use io;

/**
 * Factorial of a non-negative integer.
 * @param n {int} the operand (assumed >= 0)
 * @return {int} n!
 */
func fact(n as int) {
    if ($n == 0) {
        return 1;
    }
    return $n * fact($n - 1);
}

for (def i as int init 0; $i <= 8; $i = $i + 1) {
    io.printf("%d! = %d\n", $i, fact($i));
}

Everything in this example follows the rules above: 1TBS braces, 4-space indent, spaces around binary operators, double-quoted strings, expanded blocks, and a doc comment on the func. jennifer fmt will produce this output byte-for-byte from any equivalent input.

Comments, blank lines, and the shebang on line 1 all survive a fmt round-trip. The SPDX header (# SPDX-License-Identifier: ...) and any inline # why notes you keep alongside the code are re-emitted at their original positions: leading comments stay on the line above their attached statement, trailing same-line comments stay on the same line, and runs of blank lines collapse to one (matching the “never more than one consecutive blank line” rule).

Best practices

Stylistic guidance for writing Jennifer that reads well, ages well, and fits the way the language is shaped. Each entry is a heuristic, not a hard rule - the language won’t stop you, but the rule of thumb is there because the alternative tends to bite later.

Follow the style guide

The single biggest readability win is uniform source style across a codebase. When every file uses the same spacing, brace placement, and naming, the eye learns the shape of well-formed Jennifer and starts spotting bugs from rhythm alone - a one-off indent or a stray space becomes a signal. The reverse is also true: every codebase that tolerates “personal style” eventually pays for it in review friction, merge conflicts over whitespace, and reader-time spent on the wrong question (“is this code unusual because it does something unusual, or just because the author indents differently?”). Pick the agreed style once, then stop thinking about it.

Jennifer ships its style as both a written spec and an enforcement tool: read Style guide for the canonical rules (spacing, braces, naming, literal layout), then run jennifer fmt to make any file conform. Running fmt on save - or at minimum before every commit - is the cheapest habit you can adopt; it removes style from the list of things you and your reviewers have to think about.

Lint for suspect patterns with jennifer lint

fmt fixes how code looks; jennifer lint flags what it does that is legal but probably wrong. It sits between the formatter and the parser: the code parses and runs, but something is still worth a second look. Each check has a stable ID, grouped by concern - the leading digit is the group: L0nn source errors, L1nn correctness, L2nn complexity and style, L3nn API lifecycle:

The L0nn source errors are always on - you can’t disable “the file doesn’t parse”. They report in whatever --format you ask for, so a --format=json pipeline gets valid output even when a file is broken. Everything else (L1nn/L2nn/L3nn) is selectable:

jennifer lint myprogram.j                 # human-readable, with source carets
jennifer lint --format=json app.j         # JSON array of findings, for editors/CI
jennifer lint --checks=!L201,!L202 app.j  # run everything except the two style checks

The exit code follows gofmt -l / shellcheck: 0 clean, 1 when there are findings (a source error counts), 2 only when the invocation itself is broken (bad flags, unreadable file, bad --checks). That makes jennifer lint a natural pre-commit or CI gate.

When a flag is a deliberate choice, silence it in place rather than disabling the check everywhere - the ID keeps the intent greppable. The directive sits on the line the finding anchors to: usually the offending statement, but the func line for L201 and the block-introducer line for L202:

try { risky(); } catch (e) { }   # lint-disable: L103

A # lint-disable-file: L201, L202 at the top of a file silences those IDs file-wide, and a .jennifer-lint file at your project root sets defaults for every run (same IDS / !IDS format, one direction). There is no blanket “disable everything” - a directive always names the IDs it turns off, so a reviewer can see exactly what was waved through. A doubled marker (## lint-disable: ...) is just a comment, not a directive - handy for writing about a directive. examples/linting.j demonstrates every check and its suppression.

Why 4+ levels of nesting is a code smell

The flexibility that lets list of list of int hold any shape gets unreadable fast as you nest deeper. Here’s a four-level type holding “per game, per player, per character, per inventory slot, the item name”:

def saves as list of list of list of list of string init [
    [[["sword", "shield"], ["bow"]], [["dagger"]]],
    [[["staff", "amulet"]], [[], ["potion", "rope", "torch"]]]
];

# What does this even mean?
$saves[0][1][0][0] = "axe";

Three problems:

1. No semantic names for the dimensions. Is index 2 “the character” or “the inventory slot”? You can’t tell without going back to read the declaration and counting brackets.
2. Bug-prone access. $saves[0][1][0][0] is four indices that all look the same. Off-by-one or off-by-level errors are silent until the program either panics or, worse, modifies the wrong slot.
3. Inflexible. Adding a fifth dimension (per save slot, per timestamp, …) means rewriting every access site in the program.

The standard fix is a struct or named record (see Structs). Other options that work without introducing a new type:

• Wrap access in methods: getItem(save, player, character, slot) reads better than four bare brackets and gives you one place to fix a bug. Internally the function still walks the nested lists, but call sites are self-documenting.
• Flatten with composite keys: map of string to string keyed on "save:0/player:1/char:0/slot:0" trades index speed for name clarity. Better when the structure is sparse anyway.
• Decompose into parallel simpler structures: one list of save metadata, one map from save-id to inventory, etc.

As a rule of thumb: one level is normal, two is fine, three is uncommon, four is almost always a sign there’s a missing abstraction.

Examples

The repository’s examples/ directory holds these plus many more (showcase.j, wordcount.j, encoding.j, net.j, archive.j, …) - all golden-tested by cmd/jennifer/examples_test.go.

Strings

# greeting.j
use io;

def name as string init "Jennifer";
io.printf("hello, " + $name + "!\n");

Output:

hello, Jennifer!

FizzBuzz

# fizzbuzz.j
use io;

for (def i as int init 1; $i <= 15; $i = $i + 1) {
    if ($i % 15 == 0) {
        io.printf("FizzBuzz\n");
    } elseif ($i % 3 == 0) {
        io.printf("Fizz\n");
    } elseif ($i % 5 == 0) {
        io.printf("Buzz\n");
    } else {
        io.printf("%d\n", $i);
    }
}

Factorial (recursion + parameters)

# factorial.j
use io;

func fact(n as int) {
    if ($n == 0) { return 1; }
    return $n * fact($n - 1);
}

for (def i as int init 0; $i <= 8; $i = $i + 1) {
    io.printf("%d! = %d\n", $i, fact($i));
}

More substantive examples

For programs that exercise the full feature surface - lists, maps, iteration, the core and strings libraries - see examples/showcase.j (every feature in one file) and examples/wordcount.j (word-frequency analyzer with histogram, nested aggregation, and a 3x3 grid demo). Both are part of the golden test suite.

Jennifer libraries

Jennifer’s standard library is split into topic-based libraries. Each is enabled explicitly with use NAME;; nothing is auto-loaded. This page catalogs every library that ships with the interpreter and links to the reference doc for each.

Looking for one specific function? See the cheatsheet - alphabetical list of every builtin with its library and a one-line description.

len is a language built-in primary, not a library function. Use it from any program with no use statement; it’s polymorphic over string / list / map / bytes.

The TinyGo column reports whether the library runs in full on the constrained jennifer-tiny binary (TinyGo-built). A partial entry links to ../technical/tinygo.md for the restriction list; the default jennifer binary (standard Go) always supports the full surface.

net’s “stubs only” is about the stock jennifer-tiny build, which ships no network driver - not a TinyGo limitation. A tiny build rebuilt with a network stack runs net too; see the note on net and TinyGo.

A quick taste:

use io;
use math;
use meta;
use strings;

io.printf("Jennifer %s\n", meta.VERSION);
io.printf("pi is roughly %f\n", math.PI);
io.printf("math.sqrt(2) = %f\n", math.sqrt(2));
io.printf("upper: %s\n", strings.upper("hello"));
io.printf("len: %d\n", len("hello"));           # language built-in, no import

Namespace-first registration

Every library is namespaced: each name is reachable as lib.name(...) (call) or lib.NAME (constant). The library’s name doubles as the namespace prefix at the use site.

Aliasing (use lib as alias;) is a rename, not an addition: after the alias the canonical name no longer resolves at call sites (it errors with a “did you mean alias?” hint). The canonical name is also freed for use as an ordinary identifier, just like Python’s import foo as bar.

(core used to be auto-loaded and exposed len / JENNIFER_VERSION as bare globals via RegisterGlobal / RegisterGlobalConst. len was promoted to a language built-in keyword, version constants moved to meta, and core was deleted. The RegisterGlobal* API surface remains on Interpreter but is unused by any shipping library; it gets removed in a later cleanup pass.)

How libraries are organized

The standard library favors many small, focused libraries over a few large ones. The organizing principle, captured for future extensions:

• Touches I/O (stdin/stdout/files/network/clock) -> io (which can later split into fs, net, time as it grows).
• Pure value transformation across kinds -> convert.
• Pure numeric -> math (includes the non-crypto random helpers).
• String manipulation -> strings.
• List manipulation -> lists.
• Map manipulation -> maps.
• Operating-system glue (env, args, host info) -> os.
• Interpreter-self-identity constants (version, build, future build-time / git-sha / GC stats) -> meta.
• Time / instants / durations -> time (formatting, parsing, and fixed-offset zones).
• Cryptographic-style digests (MD5, SHA-1, SHA-256) -> hash. Non-cryptographic checksums (CRC-32, CRC-64) -> crc. The split keeps “transport integrity” and “content addressing” visible at the import line.
• Byte / string introspection and character-set codecs (ASCII, ISO-8859-1, Windows-1252, EBCDIC IBM-1047) plus hex / base64 binary-to-text -> encoding (long-tail codecs parked for later).
• Observing / joining background computations launched with spawn -> task. Concurrency itself is a language feature (the spawn keyword + task of T type); the library is just the observation surface.
• Filesystem I/O (whole-file reads/writes, metadata, directory operations, buffered file handles) -> fs. Blocking on purpose; non-blocking use composes with spawn.
• Network I/O (TCP + UDP sockets, DNS lookups) -> net. Blocking calls, same spawn-composition story as fs. The stock jennifer-tiny binary returns friendly “use the default jennifer” errors because it ships no network driver - a build choice, not a TinyGo limitation; a tiny build with a network stack runs net too.
• Regular expressions over string -> regex. RE2 syntax (Go’s regexp engine); implicit LRU cache. Pure string processing, no other library dependencies.
• Test-runner primitives (name-based method dispatch, per-process result accumulator, format dispatcher for text/TAP/JUnit) -> testing. Lives here because Jennifer has no function references yet; the .j-side assertion vocabulary and CLI harness ship on top of these primitives.
• A genuinely new topic with five or more functions / constants -> a new library. Fewer than five names fold into the most-related existing library (the non-crypto random helpers were the first case the rule caught - they live under math.rand* rather than getting their own library).
• A single function with no clear topic -> the most-related existing library.
• Genuinely polymorphic structural primitives that every program needs (len) -> language built-in keyword, not a library. The bar is intentionally high; len is the only one.

Naming convention

Library names look mixed at first glance - strings is plural but math is singular. The rule:

• Plural for count nouns: when the library operates on instances of something you can have multiples of. strings, lists, maps, bytes, files.
• Singular for mass nouns and conceptual wholes: math, meta, time, regex (planned).
• Bare verb when the library is named for what it does, not what it touches: convert.
• Idiomatic abbreviations are fine: os, fs, net, regex.

Three practical constraints reinforce the count/mass rule:

1. Type keywords are reserved. string, int, float, bool, list, map, null cannot be library names because they tokenize as type tokens, not IDENTs. The plural form (strings, lists, maps) sidesteps this naturally.
2. The rule matches Go’s stdlib: strings and bytes are plural; math, io, os are singular. Since the interpreter is written in Go, the convention transfers cleanly to library author intuition.
3. Within a library, function names are lowercase / camelCase (upper, startsWith, typeOf). Constants are uppercase (PI, E, VERSION, PLATFORM).

For implementation notes on how libraries register themselves with the interpreter (RegisterNamespaced, the use-gated lookup), see ../technical/interpreter.md > Builtins and libraries.

For canonical terminology (library vs module, function vs method, list vs array, …), see ../glossary.md. This page uses the terms in that table.

Cheatsheet - all builtins at a glance

Alphabetical index of every standard-library function and constant. Use it when you know the name and want to know which library and how to call it; use each library’s own page when you want to read about a topic. Each row’s library prefix links to the per-library doc.

The table covers what ships with the interpreter. New entries land here at the same time as the per-library doc - it’s a flat lookup view, not authoritative.

Functions

Constants

Type-conversion calls

int, float, string, bool are also type keywords (used in def x as int). The parser allows them in expression position only when immediately followed by (, so def x as int init convert.toInt("42"); works but def x as int init int; errors. See convert.md for the parser detail.

See also

• index.md - library catalog with code samples and the organizing principles.
• Per-library reference pages: io.md, convert.md, math.md, strings.md, lists.md, maps.md, os.md, meta.md, time.md, hash.md, crc.md, encoding.md, task.md, fs.md, net.md, regex.md, testing.md.
• ../user-guide/imports.md - how to import a library in a Jennifer source file.

archive - tar / zip containers

Enable with use archive;. Bundle files into a tar or zip container and read them back, entirely over bytes - no fs dependency, value-semantic. Shares the pack / unpack verbs with compress (byte streams there, file bundles here); the container format is a string argument. Backed by Go’s archive/tar + archive/zip; works on both binaries.

Surface

format is "tar", "zip", or the gzip combo "tar.gz" (alias "tgz"). An unknown format, or corrupt input to unpack, is a positioned runtime error (catchable with try / catch).

archive.Entry

A struct { name as string, data as bytes, mode as int, mtime as int }:

• name - the path within the archive (subdirectories with /).
• data - the file contents.
• mode - unix permission bits (e.g. 0o644); 0 means the default 0o644.
• mtime - modification time, unix seconds.

Only regular files map to an Entry; directory members are skipped on unpack.

Example

use io;
use archive;
use convert;

def readme as archive.Entry init archive.Entry{
    name: "README", data: convert.bytesFromString("hello", "utf-8"), mode: 0o644, mtime: 0
};
def blob as bytes init archive.pack([$readme], "tar.gz");   # one call: tar, then gzip
def back as list of archive.Entry init archive.unpack($blob, "tar.gz");
io.printf("%s = %s\n", $back[0].name, convert.stringFromBytes($back[0].data, "utf-8"));

"tar.gz" layers compress’s gzip over a tar internally, so the everyday .tar.gz case is a single call rather than a tar-then-gzip pair.

See also

• compress.md - pack / unpack for byte streams ("gzip" / "zlib" / "deflate").
• fs.md - write the packed bytes to disk, or read an archive off disk to unpack.

compress - byte-stream compression

Enable with use compress;. gzip, zlib, and raw DEFLATE - bytes in, bytes out - plus a streaming compressor for large data. The algorithm is a string argument, the same shape as hash.compute(b, "sha-256") and crc.compute(b, "crc32"); the pack / unpack verbs pair with archive’s (byte streams here, file bundles there). Distinct from encoding, which is reversible representation (hex / base64, which don’t reduce information); this is entropy-based size reduction. Backed by Go’s compress/*; works on both binaries.

Surface

level is optional: "fast", "default" (when omitted), or "best". Decompressing malformed input, or an unknown algo, is a positioned runtime error (catchable with try / catch).

The three algorithms:

• "gzip" (RFC 1952) - magic + CRC-32 + size. gzip(1)-compatible; the reliable HTTP Content-Encoding: gzip. Use for standalone files.
• "zlib" (RFC 1950) - a compact DEFLATE + Adler-32 wrapper. This is what HTTP Content-Encoding: deflate officially means (and it’s the wrapper inside PNG, zip entries, etc.) - but that coding is inconsistently implemented in the wild, so prefer "gzip" for HTTP.
• "deflate" (RFC 1951) - raw DEFLATE, no framing. Smallest, when you supply your own framing. Not the HTTP deflate content-coding despite the name - that one is "zlib".

One-shot

use io;
use compress;
use convert;

def raw as bytes init convert.bytesFromString("hello hello hello world", "utf-8");
def packed as bytes init compress.pack($raw, "gzip", "best");
def back as bytes init compress.unpack($packed, "gzip");
io.printf("%t\n", convert.stringFromBytes($back, "utf-8") == "hello hello hello world");

Streaming

Feed input in chunks (so you never hold it all at once); the full compressed result comes back at finalize:

def s as compress.Stream init compress.stream("gzip");
compress.update($s, chunkOne);
compress.update($s, chunkTwo);
def packed as bytes init compress.finalize($s);   # equals compress.pack of the concatenation

compress.Stream is a handle (like hash.Stream): copies share the underlying state, and finalize consumes it - a second finalize or update on the same handle errors.

See also

• encoding.md - hex / base64 (representation, not compression).
• hash.md - the same algo-string + streaming-handle shape.
• archive.md - pack / unpack for file bundles ("tar" / "zip").

convert - explicit type conversion

Enable with use convert;. Provides one-argument conversion functions plus typeOf for runtime kind introspection. Every function either returns the converted value or produces a positioned runtime error.

use io;
use convert;

def n as int init convert.toInt("42");        # parse string -> 42
def f as float init convert.toFloat(5);       # int -> 5.0
def s as string init convert.toString(3.14);  # any -> "3.14"
def b as bool init convert.toBool(0);         # 0 -> false

io.printf("%s\n", convert.typeOf(5 / 2));      # "float" (after Python 3 / change)
io.printf("%s\n", convert.typeOf(5 // 2));     # "int"

Behavior summary

bytesFromString / stringFromBytes are the UTF-8 cross-kind pair (string to bytes and back) - the one codec every program needs. Every other character encoding (ISO-8859-, Windows-, EBCDIC) and the binary-to-text codecs (hex, base64, quoted-printable) live in encoding: encoding.encode / decode and encoding.toText / fromText.

toCodepoint / fromCodepoint: code point, not “character”

These convert between a single code point (a Unicode scalar value, an int) and the one-rune string that holds it - the primitive a Unicode algorithm needs (Punycode digits, a \x01 control byte, an escape). Two things worth being precise about:

• The whole range works, not just ASCII or the BMP. fromCodepoint accepts any scalar value 0..0x10FFFF (hex literals are fine: fromCodepoint(0x20AC) is €, fromCodepoint(0x1F602) is 😂). The result is one rune whose UTF-8 encoding is 1 to 4 bytes - a code point is not a byte. Only a negative value, one above 0x10FFFF, or a UTF-16 surrogate (0xD800..0xDFFF) errors.
• “One rune” is not “one character a reader sees.” A user-perceived character - a grapheme cluster - can be several code points: a base plus combining marks (e + U+0301 = é), an NFD-decomposed accent, an emoji ZWJ sequence (👨‍👩‍👧). Each of those code points round-trips individually, but toCodepoint takes exactly one code point, so it rejects a multi-rune cluster the same way it rejects "ab". len, strings.chars, and strings.substring are all rune-indexed too (see strings.md); Jennifer has no grapheme-cluster API. The tell: precomposed é (U+00E9) is len 1 and toCodepoint gives 233; decomposed é (e + U+0301) is len 2 and toCodepoint errors.

Errors

• convert.toInt("abc") - parse failure (string doesn’t represent a valid integer).
• convert.toInt(null) - no conversion defined.
• convert.toInt(f) for a NaN, +/-Infinity, or out-of-int64-range float - the value has no representable integer (truncation would be garbage).
• convert.toBool("maybe") - strings: only "true" and "false" accepted.
• convert.toBool(123), convert.toBool(-1) - ints: only 0 and 1 accepted.
• convert.toBool(1.5) - floats: only 0.0 and 1.0 accepted.
• convert.stringFromBytes(b, "utf-8") on bytes that aren’t valid UTF-8 - strict at boundaries; no silent replacement characters.
• convert.bytesFromString(s, "iso-8859-1") or any non-"utf-8" codec name - rejected as unsupported; use encoding.encode / decode for those.
• Arity errors (too many or too few arguments).

For “any nonzero counts as true” semantics, write the comparison explicitly:

def b as bool init $count != 0;     // not convert.toBool($count)

This matches the strict-conditions rule everywhere else in Jennifer - if you want to project an arbitrary value into a bool, state the criterion.

Notes on the verb naming

The convert library’s four conversion callees are named toInt, toFloat, toString, toBool (not int / float / string / bool) so they don’t collide with the type keywords - the parser keeps those reserved for declarations (def x as int ...). The to-prefixed verb also reads as English at the call site: convert.toInt("42") says “convert to int.” typeOf is a normal identifier and is not a type keyword.

Writing the bare form (int("42"), string(42), …) is a parse error directing you at the convert.to* form.

Objects: typeOf vs objectType

Some libraries hand back an opaque object - a value that carries data but exposes it only through that library’s own accessors, not through operators or [index] / .field. The first is json.Value (from json.decode). For any such value convert.typeOf returns the generic "object", and convert.objectType returns the specific registered name so you can tell one object family from another:

def doc as json.Value init json.decode("{}");
io.printf("%s\n", convert.typeOf($doc));       # object
io.printf("%s\n", convert.objectType($doc));   # json.Value

convert.objectType errors on a non-object, so guard with convert.typeOf(v) == "object" first if the kind is unknown.

See also: encoding.md (all other character and binary-to-text codecs), ../user-guide/index.md, ../technical/interpreter.md, index.md.

crc - cyclic redundancy checks

Enable with use crc;. Computes CRC-32 (IEEE polynomial) and CRC-64 (Go’s crc64.ECMA polynomial) checksums over bytes, matching the codec-table shape used by hash. Output is the natural-width digest in big-endian byte order.

CRCs are designed to catch transport / storage corruption, not to resist deliberate tampering. For content-addressing or signature work, use hash (MD5, SHA-1, SHA-256). The library split keeps the difference visible at the import line.

use io;
use convert;
use crc;

def input as bytes init convert.bytesFromString("abc", "utf-8");
def sum as bytes init crc.compute($input, "crc32");
io.printf("crc32 checksum is %d bytes\n", len($sum));

Algorithm selection

Note: the “CRC-64/XZ” vector you may see elsewhere (6c40df5f0b497347 for "123456789") uses a different polynomial. We ship Go’s stdlib choice (995dc9bbdf1939fa for the same input).

Output bytes are big-endian (network byte order). The convention matches the natural display of Sum() from Go’s CRC types and removes any ambiguity at the call site.

Passing an unknown algorithm is a positioned runtime error: crc.compute: unknown algorithm "adler32"; known: "crc32", "crc64".

One-shot

Streaming

Feed chunks into a stream handle and finalize. Same shape as hash:

use crc;
def s as crc.Stream init crc.stream("crc32");
crc.update($s, $chunkOne);
crc.update($s, $chunkTwo);
def sum as bytes init crc.finalize($s);

Errors

• Wrong arity: crc.compute expects 2 arguments (bytes, algo), got 1.
• Wrong scalar type: crc.compute: first argument must be bytes, got string.
• Unknown algorithm: crc.compute: unknown algorithm "adler32"; known: "crc32", "crc64".
• Reuse of a finalized stream: crc.update: stream 3 has already been finalized or never existed.

All errors are positioned at the call site.

See also

• hash.md - cryptographic-style digests (MD5, SHA-1, SHA-256).
• milestones.md - ships hash/crc.

encoding - introspection + text and character codecs

Enable with use encoding;. Three groups of functions:

1. Introspection - rune count vs byte count, and an ASCII test.
2. Binary-to-text (toText / fromText) - hex, base64, and quoted-printable, bytes to a printable string and back.
3. Character codecs (encode / decode) - a Jennifer string to and from a single-byte legacy encoding (ISO-8859-, Windows-, EBCDIC).

The cross-kind UTF-8 codec ships with convert (convert.bytesFromString / convert.stringFromBytes); this library is where the rest of the codec proliferation lives.

use io;
use convert;
use encoding;

def src as bytes init convert.bytesFromString("café", "utf-8");
io.printf("%s\n", encoding.toText($src, "hex"));            # 636166c3a9
io.printf("%t\n", encoding.isAscii($src));                 # false
io.printf("%x\n", encoding.encode("café", "iso-8859-1"));  # 63 61 66 e9

Introspection

Binary-to-text: toText / fromText

One verb pair, the encoding named by a string. Reversible representation - these grow or reshape the bytes, they don’t reduce information (that’s compress).

Formats

Quoted-printable keeps printable ASCII literal, turns =, control, and 8-bit bytes into =XX, and soft-wraps lines to 76 columns with a trailing =. Decode reverses it, tolerant of both CRLF and LF soft breaks, and round-trips bytes.

Format names are exact (case-sensitive, no - / _ normalisation) - they’re the library’s own fixed set, not external standards with variant spellings. "base64" works; "BASE64" errors with the supported set listed.

Why a format string instead of encoding.hex() / encoding.base64()? Jennifer’s letters-only identifier rule rejects digits in method names, so encoding.base64 won’t parse; and the codec-table shape already matches the rest of this library plus convert, hash, and crc.

Character codecs: encode / decode

Convert a Jennifer string to and from a named single-byte encoding.

Codec set

Every codec below is single-byte: one byte maps to one rune. Bytes with no assignment in a codec (some Windows code pages have a few) are a positioned error on decode; runes with no byte are a positioned error on encode.

ASCII and EBCDIC

ISO/IEC 8859 (single-byte Latin and script families)

(There is no iso-8859-12; the draft was abandoned.)

Windows code pages

Codec names are exact

Codec names are exact-match - the one canonical spelling only, no case-folding, separator-stripping, or IANA aliases. "iso-8859-1" works; "latin-1", "ISO-8859-1", "iso88591", and "cp1252" all error with the known set listed. This is deliberate strictness (stance #2, explicit over implicit): a codec is named one way, and no lenient spelling hides a typo. Map an external name (an HTTP charset=ISO-8859-1, say) to the canonical form yourself before calling.

How the tables are built

Only ascii (7-bit, with its own out-of-range errors) and ebcdic (IBM-1047, not in the standard Unicode mapping path) are hand-written. Every ISO-8859 and Windows single-byte codec - including iso-8859-1 and windows-1252 - is generated from the Unicode Consortium mapping files, so every table comes from one authoritative source rather than being hand-transcribed:

go generate ./internal/lib/encoding/   # writes codecs_gen.go

Converting a text file

Jennifer strings are UTF-8 internally, so converting a legacy-encoded file to UTF-8 is just decode-then-write - there’s no separate “encode to UTF-8” step:

use fs;
use encoding;

def raw as bytes init fs.readBytes("legacy.txt");               # Windows-1252 bytes
def text as string init encoding.decode($raw, "windows-1252"); # -> a UTF-8 string
fs.writeString("utf8.txt", $text);                             # written as UTF-8

The reverse (UTF-8 to a single-byte encoding) is encoding.encode(text, codec), which errors if a character has no byte in the target codec.

Length and memory

encode / decode / toText / fromText are one-shot: each takes the whole input and builds the whole output in memory, so both are held at once. There is no fixed cap - a Jennifer string / bytes is a Go string / []byte, bounded only by available memory. For a file too large to hold twice over, note that the single-byte codecs decode each byte independently, so decoding can be split at any byte boundary: read the file in fixed-size byte chunks, decode each, and append to the output. (Encoding the other way must instead split on rune boundaries, since a UTF-8 character can span several bytes.)

Errors

• Wrong arity: encoding.encode expects 2 arguments (string, codec), got 1.
• Wrong scalar type: encoding.encode: first argument must be string, got bytes.
• Unknown codec (the message lists every registered name): encoding.encode: unknown codec "klingon"; known: "ascii", "iso-8859-1", ....
• Unrepresentable rune on encode: encoding.encode (ascii): rune U+00E9 at byte position 3 is outside ASCII (0x00..0x7F).
• Undefined byte on decode: encoding.decode (windows-1252): byte 0x81 at position 0 has no mapping in windows-1252.
• Invalid UTF-8 to lenRunes: encoding.lenRunes: input is not valid UTF-8.

All errors are positioned at the call site.

See also

• convert.md - the UTF-8 pair (bytesFromString / stringFromBytes).
• compress.md - size reduction (distinct from representation).
• hash.md, crc.md - digests whose output you’ll often encoding.toText($digest, "hex").

fs - filesystem I/O

Enable with use fs;. Blocking whole-file reads and writes, filesystem metadata, directory operations, and buffered file handles for line-oriented reads. Non-blocking use composes with spawn rather than duplicating each call as a *Async variant.

use io;
use fs;

fs.writeString("hello.txt", "hi, world\n");
def content as string init fs.readString("hello.txt");
io.printf("%s", $content);

One-shot operations

Whole-file reads and writes. Cheap to write, cheap to read.

Reading a file that doesn’t exist is a positioned runtime error; use fs.exists(path) first when the “missing file is normal” case matters.

Metadata

Boundary-friendly predicates plus a full fs.stat.

fs.Stat

def struct fs.Stat {
    path as string,        # the path as passed to fs.stat / fs.walk
    size as int,           # bytes; -1 for directories
    isDir as bool,
    mtimeNanos as int,     # Unix nanoseconds
    mode as int            # POSIX permission bits (e.g. 0o644, 0o755)
};

mtimeNanos is deliberately an int, not a time.Time - that keeps fs decoupled from the time library at the Go-package level. Composition is one line:

use fs;
use time;

def stat as fs.Stat init fs.stat("hello.txt");
def modified as time.Time init time.fromUnixNanos($stat.mtimeNanos);
io.printf("modified: %s\n", time.iso($modified));

size is -1 for directories so callers don’t accidentally interpret it as “empty directory.”

Directory operations

The library ships two verbs each for create and delete (mkdir / mkdirAll, remove / removeAll). The safe non-recursive form keeps the short name; the recursive form gets an explicit second name so a code review can grep for the risky sites. This is Jennifer’s “no footguns” stance applied at the API level - a bool parameter or a mode string would obscure the recursive intent at the call site.

use fs;

# Safe: mkdir refuses to create with missing parents.
fs.mkdirAll("build/output/cache");        # explicit intent

# Safe: remove refuses to delete non-empty directories.
fs.removeAll("build/output/cache");       # explicit intent

File handles

For line-oriented reads and files that don’t fit comfortably in memory, fs.open returns an fs.File handle backed by the integer-registry pattern also used by hash.Stream and crc.Stream.

def struct fs.File { id as int };

Mode strings use the codec-table shape:

Unknown mode strings error with the known set listed.

Handle surface

The canonical read-loop:

use io;
use fs;

def f as fs.File init fs.open("input.txt", "read");
while (not fs.eof($f)) {
    def line as string init fs.readLine($f);
    io.printf("[%s]\n", $line);
}
fs.close($f);

fs.readLine on a handle whose next read is EOF errors with end of input; the fs.eof($f) guard is what keeps the loop tight. fs.eof looks one byte ahead (through the buffered reader) so a file ending cleanly with \n still trips the guard after the last line comes out.

Polymorphic verbs (path vs handle)

Three verbs are polymorphic on the first argument’s kind:

The dispatcher picks based on whether the first argument is a string (path form) or an fs.File (handle form). Any other kind is a positioned boundary error.

Handles share state between copies

An fs.File{id} value is small; copies share the underlying Go *os.File state via the integer id. This mirrors the task of T carve-out to the “value semantics everywhere” rule:

def a as fs.File init fs.open("x.txt", "read");
def b as fs.File init $a;             # `b` and `a` reference the same file
fs.close($a);                          # closes for both
def s as string init fs.readLine($b);  # errors: id is not open

Handles are the second “handles wrap shared state” carve-out in the language, sitting alongside task of T. Every other type keeps whole-value semantics.

Concurrency composition

fs is blocking on purpose. Non-blocking use is a one-line composition with spawn:

use fs;
use task;

def t as task of string init spawn {
    return fs.readString("/etc/hosts");
};
def content as string init task.wait($t);

Multiple files in parallel:

use fs;
use task;

func loadOne(path as string) {
    return fs.readString($path);
}

def paths as list of string init ["a.txt", "b.txt", "c.txt"];
def tasks as list of task of string init [];
for (def p in $paths) {
    $tasks[] = spawn { return loadOne($p); };
}
def contents as list of string init task.waitAll($tasks);

Under the default jennifer binary this actually parallelises across cores; under jennifer-tiny (TinyGo, cooperative single-threaded 0.41) the composition is correct but sequential. See ../technical/tinygo.md.

Errors

Every error is positioned at the Jennifer call site with the path or handle id in the message.

• Missing files on fs.readString / fs.readBytes / fs.stat: fs.readString: PATH: open PATH: no such file or directory.
• Non-empty directory given to fs.remove: fs.remove: PATH: directory not empty. Use fs.removeAll for recursive delete.
• Missing parent given to fs.mkdir: fs.mkdir: PATH: no such file or directory. Use fs.mkdirAll for mkdir -p.
• Wrong mode for op: fs.readLine: fs.File "x.txt" was opened in mode "write"; open with mode "read" to read. Same message shape in reverse for read-mode handles given a write op.
• Unknown mode string: fs.open: unknown mode "rw"; known: "read", "write", "append".
• Use after close: fs.readLine: fs.File id 3 is not open (already closed, or never opened).
• Non-negative int required: fs.readChars: n must be non-negative, got -1.

Every error is catchable with try / catch:

try {
    def s as string init fs.readString("optional-config.toml");
} catch (e) {
    io.printf("no config, using defaults: %s\n", $e.message);
}

What’s not in v1

Recorded so the design decisions stay visible; ships if a concrete workload forces it.

• Streaming line iterator (for (def line in fs.lines(path))). Compose with fs.open + while (not fs.eof).
• fs.copy(src, dst) and fs.chmod(path, mode).
• Symlink ops (fs.readlink, fs.symlink).
• fs.stat($f) on an open handle. Only path-based fs.stat in v1.
• Watch / notify (inotify / kqueue / FSEvents).
• Temp file / dir creation helpers (fs.tempFile, fs.tempDir). Use os.getEnv("TMPDIR") plus your own naming.
• Follow symlinks in fs.walk. Symlink-loop protection is the reason for the deferral; a follow=true flag or a distinct fs.walkFollowing verb ships once the story is clear.

See also

• ../user-guide/concurrency.md - the spawn-and-compose story fs builds on.
• task - observe handles produced by spawn.
• time - time.fromUnixNanos converts fs.Stat.mtimeNanos into a time.Time.
• os - process-level operations that pair with fs: env vars, argv, external commands.
• ../milestones.md - design spec.

hash - cryptographic-style digests

Enable with use hash;. Computes fixed-size digests over bytes using common cryptographic-style algorithms (MD5, SHA-1, SHA-256). Output is raw bytes; users hex- or base64-encode through the encoding library when they need a string representation.

For non-cryptographic checksums (transport integrity rather than content addressing), use crc instead. The split makes the semantic difference visible at the import line.

use io;
use convert;
use hash;

def input as bytes init convert.bytesFromString("abc", "utf-8");
def digest as bytes init hash.compute($input, "sha256");
io.printf("sha256 digest is %d bytes\n", len($digest));

Algorithm selection

The library uses the codec-table shape - one verb per category, with the algorithm passed as a string. The shape mirrors convert.bytesFromString(s, "utf-8") and encoding.encode(s, codec). Algorithm names are lowercase.

Passing an unknown algorithm is a positioned runtime error that lists the supported set: hash.compute: unknown digest algorithm "md4"; known: "md5", "sha1", "sha256", "sha512".

One-shot

HMAC

hash.hmac(key, message, algo) computes the keyed-hash message authentication code (RFC 2104) - the primitive behind JWT (HS256), TOTP, AWS SigV4, and webhook signatures. key and message are bytes; the result is the raw MAC as bytes (hex / base64 via encoding, matching compute).

use hash;
use convert;
use encoding;

def key as bytes init convert.bytesFromString("secret", "utf-8");
def msg as bytes init convert.bytesFromString("payload", "utf-8");
def mac as bytes init hash.hmac($key, $msg, "sha256");
io.printf("%s\n", encoding.toText($mac, "hex"));

To verify, recompute the MAC over the same message and compare it to the received one (comparing the full digests, not a prefix).

Streaming

For inputs that don’t fit comfortably in memory (files, large network reads), feed chunks into a stream handle and finalize:

use hash;
def s as hash.Stream init hash.stream("sha256");
hash.update($s, $chunkOne);
hash.update($s, $chunkTwo);
def digest as bytes init hash.finalize($s);

hash.Stream carries an integer id field that indexes into a Go-side map of live state. Users should not read or mutate the field; pass the struct around as an opaque token.

Composing through convert and (future) encoding

No convenience wrappers like hash.md5String(s) ship. Stance #1 “one way per thing”: strings become bytes through convert.bytesFromString, the digest stays as bytes, and the user hex-encodes through encoding.hex. The example examples/hash.j carries a tiny inline bytesToHex helper for printing until encoding ships.

Errors

• Wrong arity: hash.compute expects 2 arguments (bytes, algo), got 1.
• Wrong scalar type: hash.compute: first argument must be bytes, got string.
• Unknown algorithm: hash.compute: unknown digest algorithm "md4"; known: "md5", "sha1", "sha256".
• Reuse of a finalized stream: hash.update: stream 3 has already been finalized or never existed.

All errors are positioned at the call site.

See also

• crc.md - non-cryptographic checksums (CRC-32, CRC-64).
• milestones.md - hash/crc, encoding for hex/base64 round-trips, and key-based crypto.

httpd - HTTP server engine

Enable with use httpd;. An HTTP/1.1 server engine wrapping Go’s net/http, so keep-alive, chunked transfer, TLS (and HTTP/2 over TLS), request timeouts, and graceful shutdown come from the battle-tested Go stack rather than being re-implemented in the interpreter. It is the server counterpart to the net client primitives and the http client module.

Default binary only. Like net, httpd needs a network stack, so it runs on the standard jennifer build; on jennifer-tiny every call returns a friendly error (TinyGo ships no netdev driver). See technical/tinygo.md.

The pull loop

Jennifer has no first-class functions, so you cannot hand Go a request handler callback. Instead the engine accepts and parses requests concurrently on Go’s side and hands them to your program one at a time: httpd.accept blocks for the next request, and httpd.respond answers it.

use httpd;

def srv as httpd.Server init httpd.listen("127.0.0.1:8080");
while (true) {
    def req as httpd.Request init httpd.accept($srv);
    httpd.respond($req, 200, "hello\n");
}

The two concurrency worlds stay cleanly separate: Go owns the I/O concurrency (accepting, parsing, keep-alive), and your program stays a simple serial loop. When you want per-request parallelism, opt into it with your own spawn - several spawned workers can each call httpd.accept on the same server handle to form a worker pool, since the handle’s state is shared:

use httpd;
use task;

def srv as httpd.Server init httpd.listen("127.0.0.1:8080");
def workers as list of task of null init [];
for (def i in lists.range(0, 4)) {
    $workers[] = spawn {
        while (true) {
            def req as httpd.Request init httpd.accept($srv);
            httpd.respond($req, 200, "handled by a worker\n");
        }
    };
}

Surface

Each request must be answered exactly once - a second respond / serveFile / serveDir on the same request, or a setHeader after the answer, is an error.

Handles

httpd.Server and httpd.Request are {id as int} handles into a Go-side registry (the same pattern as fs, net, os.Process): value-semantic to copy, but every copy refers to the same underlying server / request. That is what lets a copied Server handle inside a spawn worker pull from the same accept queue.

A tiny JSON API

Everything the engine hands you is a value, so the rest of the standard library composes normally - here, json for the response body:

use httpd;
use json;

def srv as httpd.Server init httpd.listen(":8080");
while (true) {
    def req as httpd.Request init httpd.accept($srv);
    def out as json.Value init json.map();
    $out = json.set($out, "/method", httpd.method($req));
    $out = json.set($out, "/path", httpd.path($req));
    httpd.setHeader($req, "Content-Type", "application/json");
    httpd.respond($req, 200, json.encode($out));
}

Static files

use httpd;
def srv as httpd.Server init httpd.listen(":8080");
while (true) {
    def req as httpd.Request init httpd.accept($srv);
    httpd.serveDir($req, "./public");
}

serveDir cleans the request path so a ../ cannot climb above root; serveFile answers with one specific file regardless of the request path.

Graceful shutdown

httpd.shutdown closes the listener, wakes any workers blocked in httpd.accept (they get an error so their loops can exit), and lets in-flight requests finish before returning. A typical server installs a signal handler (via os) that calls shutdown, or shuts down after a sentinel request.

Behind a reverse proxy (nginx)

In production an httpd / web app usually sits behind nginx, which terminates TLS, serves static assets, buffers slow clients, and can load balance. nginx speaks plain HTTP to the app over either a TCP port or a Unix domain socket - httpd.listen supports both.

TCP port. The app listens on a local port; nginx proxies to it:

def srv as httpd.Server init httpd.listen("127.0.0.1:8080");

server {
    listen 443 ssl;
    server_name app.example;
    location /static/ { root /srv/app; }        # nginx serves assets directly
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}

Unix domain socket. No TCP port; nginx proxies over a socket file (cleaner permissions, a touch less overhead). The unix: prefix selects it, and a graceful httpd.shutdown unlinks the socket on the way out:

def srv as httpd.Server init httpd.listen("unix:/run/app/app.sock");

upstream app { server unix:/run/app/app.sock; }

server {
    listen 443 ssl;
    server_name app.example;
    location / {
        proxy_pass http://app;
        proxy_set_header Host $host;
    }
}

Each process handles one request at a time (the pull loop is serial per accept loop - see Scope and limits), so for concurrency and multi-core use run several app processes on distinct ports or sockets behind one nginx upstream {} block.

Scope and limits

• HTTP/1.1 over plaintext; HTTP/2 is negotiated automatically over TLS by net/http.
• The request body is buffered with a 10 MiB cap; a configurable limit and explicit read/idle/write timeout knobs are a planned follow-up.
• Routing, path parameters, middleware, cookies, and sessions are not in the engine - they belong to the web framework module built on top of it, which does name-based handler dispatch itself (the engine never calls back into the interpreter). web owns the session id cookie; the session store stays with the app, so the engine and web both stay storage-agnostic.

See also

• http - the HTTP/1.1 client module.
• net - the lower-level TCP / TLS / UDP primitives.
• json / toml - encode / decode request and response bodies.
• technical/tinygo.md - why httpd is default-binary-only.

io - input/output

Enable with use io;. It provides formatted output - printf (stdout), eprintf (stderr), and sprintf (to a string), which share a Go-style format-string mini-language - and stdin input: readLine / eof for lines, readBytes / readChars for binary.

printf

Writes formatted output to standard output. Three calling shapes:

io.printf("hi\n");                              # literal string (no verbs)
io.printf($x);                                  # single non-string value, displayed
io.printf("you are %d years old!\n", $age);     # format string + arguments
io.printf("%s = %d, ok=%t\n", "answer", 42, true);

Never pass a dynamic string as the format argument. A single string argument is always the format string, so io.printf(s) scans s for verbs. That is safe only for a string you wrote. For any value you did not author - a generated password, user input, file contents - use io.printf("%s", s) (or "%s\n"). A stray % in the data would otherwise be read as a verb: %c fails as an unknown verb, %s as a missing argument, so io.printf(password) is a latent bug. This is deliberate - there is no separate verbatim-print builtin (see technical/rejected.md); printf("%s", s) is the one canonical way to print a dynamic string.

eprintf

Exactly like printf - same argument forms and verbs - but writes to standard error instead of standard output. Use it for diagnostics, warnings, and logs that must not mix into a program’s stdout data (so a pipeline consuming the stdout stays clean).

io.eprintf("warning: retrying (%d/%d)\n", $attempt, $max);   # goes to stderr

sprintf

Same arguments as printf but returns the formatted string instead of writing it.

def msg as string init io.sprintf("%d + %d = %d", 1, 2, 3);
io.printf("%s\n", $msg);   # "1 + 2 = 3"

Format verbs

Mismatches (wrong verb for the value kind, too few or too many args, dangling %, unknown verb) all produce runtime errors.

Escaping the meta-characters:

• A literal % in any string passed to printf/sprintf must be doubled to %%.
• A literal | immediately after a verb must be doubled to ||, because | otherwise starts a modifier list (see Format modifiers). The escape consumes one of the two |s; the other appears in the output. Pipes that don’t touch a verb are normal characters and need no escaping: io.printf("a|b %s||c|d\n", "X") prints a|b X|c|d - the || after %s is the escape, while the |s in a|b and c|d sit between non-verb characters and pass through unchanged.

Format modifiers

Each verb (except %v) accepts an optional pipe-separated modifier list:

%verb[|key=value]*

Modifiers are order-independent flags - %d|pad=5|fill=0|align=right and %d|align=right|fill=0|pad=5 produce the same output. The list runs left-to-right until it hits a byte that isn’t part of a key or value. To put a literal | immediately after a verb, double it: || writes one | and ends the modifier list (same shape as %%). Unknown keys, bad values, missing companions (e.g. group= without sep=), and the same key set twice are all runtime errors.

Evaluation order within one verb:

1. Null check. If the value is null and the spec includes a null= modifier, the verb-specific render is skipped and the configured replacement is used.
2. Verb-specific render. mode, base, prec, sci, sign, group/sep, case apply here.
3. Layout. max truncates (rune-aware), then pad+fill+align extends. Layout still applies to the null replacement, so columns line up.

null= (shared by %s, %d, %f, %t)

Without a null= modifier, a null value is still a type-mismatch error against any verb except %v. null= wins over every other modifier on its verb: %s|mode=quote|null=literal("X") on a null prints X, not "X".

%s modifiers

mode=quote wraps the string in double quotes and escapes interior \, ", and control bytes. mode=escape does the same escaping without the wrapping - useful for showing a string’s structure in debug output.

io.printf("[%s|pad=8|align=right]\n", "hi");        # [      hi]
io.printf("[%s|max=3]\n", "abcdef");                # [abc]
io.printf("%s|mode=quote\n", "a\nb");               # "a\nb"

%d modifiers

io.printf("%d|base=2\n", 5);                                # 101
io.printf("%d|base=16|group=4|sep=_\n", 3735928559);        # dead_beef
io.printf("%d|pad=5|fill=0|sign=always\n", 42);             # +0042

%f modifiers

io.printf("%f|prec=2\n", 3.14159);              # 3.14
io.printf("%f|prec=4|trim=true\n", 3.0);        # 3
io.printf("%f|sci=true|prec=2\n", 0.00123);     # 1.23e-03

%t modifiers

%v modifiers

%v takes no modifiers - it is deliberately the “I don’t care, just print it” verb. Use a typed verb plus modifiers when you want to shape the output.

%a modifiers

%a is the aggregate verb: it renders a list or map in literal-like shape, recursing into nested aggregates. Non-collection input is a runtime error.

Modifier values can be double-quoted to include spaces, brackets, or other characters reserved by the modifier-list grammar. The escape set is the standard \n \r \t \\ \":

def xs as list of int init [1, 2, 3];
io.printf("%a\n", $xs);                              # [1, 2, 3]
io.printf("%a|sep=\" | \"\n", $xs);                  # 1 | 2 | 3 (with brackets)
io.printf("%a|open=\"<\"|close=\">\"\n", $xs);       # <1, 2, 3>

def grid as list of list of int init [[1, 2], [3, 4]];
io.printf("%a\n", $grid);            # [[1, 2], [3, 4]]
io.printf("%a|depth=1\n", $grid);    # [[...], [...]]

def m as map of string to int init {"a": 1, "b": 2};
io.printf("%a\n", $m);                       # {a: 1, b: 2}
io.printf("%a|kv=\"=\"|sep=\" \"\n", $m);    # {a=1 b=2}

Per-element rendering uses the same display form as %v, so primitive values inside an aggregate look the way they would in a print statement. null=skip is only valid on %a - it omits null elements entirely; the other null= modes (empty, null, literal) are rejected for %a because they don’t have a sensible per-element meaning.

Input from stdin

Three builtins for reading lines from standard input. They are output-symmetric with printf / sprintf and intentionally minimal - line at a time, with an explicit end-of-input predicate so nothing happens implicitly.

io.readLine() -> string

Read one line from stdin. The trailing \r\n or \n is stripped; the returned string never carries a newline. Calling at end-of-input is a positioned runtime error (readLine: end of input), so the caller must check io.eof() first.

A final line that has no trailing newline is returned normally on the call that reaches it; the subsequent call errors.

io.readLine(prompt) -> string

Same as io.readLine() but writes prompt to stdout (no newline added) before reading. The prompt is written unconditionally, even when stdin is piped - explicit beats silently skipping the prompt off a non-TTY.

def name as string init io.readLine("name: ");
io.printf("hi, %s\n", $name);

io.eof() -> bool

True if and only if the next io.readLine() (or io.readBytes / io.readChars) would return less than requested. Implemented by peeking one byte through a buffered reader; the byte stays in the buffer for the next read. Once true, io.eof() stays true for the rest of the run.

io.readBytes(n) -> bytes

Reads exactly n bytes from stdin and returns them as a bytes value. If EOF is hit before n bytes are available, returns the partial result and io.eof() becomes true on the next call. n must be a non-negative int.

use io;
def first as bytes init io.readBytes(8);   # exactly 8 bytes or less at EOF
io.printf("got %d bytes\n", len($first));

io.readChars(n) -> string

Reads exactly n Unicode code points from stdin, decoded from UTF-8, and returns them as a string. Same EOF behavior as readBytes (partial result, sticky io.eof()). n is a rune count, not a byte count - one Unicode character can be 1-4 bytes wide.

use io;
def first as string init io.readChars(3);  # exactly 3 runes
io.printf("got %d runes (%d bytes)\n", len($first), 0);  # len = 3

Canonical loop

use io;
while (not io.eof()) {
    def line as string init io.readLine();
    io.printf("[%s]\n", $line);
}

This is the only pattern the language asks you to learn. There is no for line in stdin shortcut, no lines() that slurps the whole stream, and io.readLine() does not return a sentinel value at EOF - they were considered and rejected because the existing trio is already complete and adding parallels would violate Jennifer’s “one way per thing” stance.

REPL limitation

The interactive REPL owns stdin via its line editor, so readLine and eof both refuse inside the REPL with a clear error:

readLine: stdin is owned by the REPL editor

A proper side-channel for REPL input is a future milestone. To play with the input functions today, put your program in a .j file and run it with stdin piped or redirected: jennifer run prog.j < input.txt.

Float display

Floats always display with a decimal point so the value’s type stays visible: 5.0 prints as "5.0", not "5". That matters most after the Python 3 division change - 4 / 2 is the float 2.0, and you can tell at a glance rather than wondering whether it’s an int.

See also: ../user-guide/index.md, ../technical/interpreter.md, index.md.

json - JSON encode / decode

Enable with use json;. RFC 8259 JSON, mapped onto Jennifer’s value model. Hand-rolled (no host encoding/json) so it works identically on both binaries.

Surface

Accessors over a decoded json.Value. Every one takes an optional trailing JSON Pointer (RFC 6901) string, relative to the passed node ("" or omitted = the node itself):