cell/CLAUDE.md

ƿit (pit) Language Project

Building

Recompile after changes: make Bootstrap from scratch (first time): make bootstrap Run cell --help to see all CLI flags.

Code Style

All code uses 2 spaces for indentation. K&R style for C and Javascript.

ƿit Script Quick Reference

ƿit script files: .ce (actors) and .cm (modules). The syntax is similar to JavaScript with important differences listed below.

Key Differences from JavaScript

• var (mutable) and def (constant) — no let or const
• == and != are strict (no === or !==)
• No undefined — only null
• No classes — only objects and prototypes (meme(), proto(), isa())
• No for...in, for...of, spread (...), rest params, or default params
• No named function declarations — use var fn = function() {} or arrow functions
• Variables must be declared at function body level only (not in if/while/for/blocks)
• All variables must be initialized at declaration (var x alone is an error; use var x = null)
• No try/catch/throw — use disrupt/disruption
• No arraybuffers — only blob (works with bits; must stone(blob) before reading)
• Identifiers can contain ? and ! (e.g., nil?, set!, is?valid)
• Prefer backticks for string interpolation; otherwise use text() to convert non-strings
• Everything should be lowercase

Intrinsic Functions (always available, no use() needed)

The creator functions are polymorphic — behavior depends on argument types:

• array(number) — create array of size N filled with null

• array(number, value_or_fn) — create array with initial values

• array(array) — copy array

• array(array, fn) — map

• array(array, array) — concatenate

• array(array, from, to) — slice

• array(record) — get keys as array of text

• array(text) — split text into individual characters (e.g., array("hello") → ["h","e","l","l","o"])

• array(text, separator) — split by separator

• array(text, length) — split into chunks of length

• text(array, separator) — join array into text

• text(number) or text(number, radix) — number to text

• text(text, from, to) — substring

• number(text) or number(text, radix) — parse text to number

• number(logical) — boolean to number

• record(record) — copy

• record(record, another) — merge

• record(array_of_keys) — create record from keys

Other key intrinsics: length(), stone(), is_stone(), print(), filter(), find(), reduce(), sort(), reverse(), some(), every(), starts_with(), ends_with(), meme(), proto(), isa(), splat(), apply(), extract(), replace(), search(), format(), lower(), upper(), trim()

Sensory functions: is_array(), is_text(), is_number(), is_object(), is_function(), is_null(), is_logical(), is_integer(), is_stone(), etc.

Standard Library (loaded with use())

• blob — binary data (bits, not bytes)
• time — time constants and conversions
• math — trig, logarithms, roots (math/radians, math/turns)
• json — JSON encoding/decoding
• random — random number generation

Actor Model

• .ce files are actors (independent execution units, don't return values)
• .cm files are modules (return a value, cached and frozen)
• Actors never share memory; communicate via $send() message passing
• Actor intrinsics start with $: $me, $stop(), $send(), $start(), $delay(), $receiver(), $clock(), $portal(), $contact(), $couple(), $unneeded(), $connection(), $time_limit()

Requestors (async composition)

sequence(), parallel(), race(), fallback() — compose asynchronous operations. See docs/requestors.md.

Error Handling

var fn = function() {
  disrupt  // bare keyword, no value
} disruption {
  // handle error; can re-raise with disrupt
}

Push/Pop Syntax

var a = [1, 2]
a[] = 3       // push: [1, 2, 3]
var v = a[]   // pop: v is 3, a is [1, 2]

C Integration

• Declare everything static that can be
• Most files don't have headers; files in a package are not shared between packages
• No undefined in C API: use JS_IsNull and JS_NULL only
• A C file with correct macros (CELL_USE_FUNCS etc) is loaded as a module by its name (e.g., png.c in a package → use('<package>/png'))
• C symbol naming: js_<pkg>_<file>_use (e.g., js_core_math_radians_use for core/math/radians)
• Core is the core package — its symbols follow the same js_core_<name>_use pattern as all other packages
• Package directories should contain only source files (no .mach/.mcode alongside source)
• Build cache files in build/ are bare hashes (no extensions)
• Use JS_FRAME/JS_ROOT/JS_RETURN macros for any C function that allocates multiple heap objects. Any JS_New*/JS_SetProperty* call can trigger GC.

Project Layout

• source/ — C source for the cell runtime and CLI
• docs/ — master documentation (Markdown), reflected on the website
• website/ — Hugo site; theme at website/themes/knr/
• internal/ — internal ƿit scripts (engine.cm etc.)
• packages/ — core packages
• Makefile — build system (make to rebuild, make bootstrap for first build)

Testing

After any C runtime changes, run all three test suites before considering the work done:

make                        # rebuild
./cell --dev vm_suite       # VM-level tests (641 tests)
./cell --dev test suite     # language-level tests (493 tests)
./cell --dev fuzz           # fuzzer (100 iterations)

All three must pass with 0 failures.

Documentation

The docs/ folder is the single source of truth. The website at website/ mounts it via Hugo. Key files:

• docs/language.md — language syntax reference
• docs/functions.md — all built-in intrinsic functions
• docs/actors.md — actor model and actor intrinsics
• docs/requestors.md — async requestor pattern
• docs/library/*.md — intrinsic type reference (text, number, array, object) and standard library modules