Shoddy Documentation

The Language Specification

The whole language, defined — with the stack core and the design rationale as appendices

The name comes from the shoddy trade of the West Riding of Yorkshire. From 1813, the mills of Ossett, Morley, and Wakefield tore worn-out rags back to fiber, in a machine called the devil. They blended that reclaimed stock with new wool and wove it into cloth again. The trade lasted until synthetic fibers ended it. The language is built the same way: old ideas reclaimed, blended with new wool, woven into something useful. The executable is the mill; the libraries are its machines. The full story is in the heritage of the name.

Shoddy is a purely functional BASIC — a language where values are made, never changed in place. Its surface syntax is typed and applicative: parenthesized calls, infix operators, Let, Fn. Underneath, every program desugars onto a concatenative (stack-based) core, in the tradition of the languages Joy and Kitten. Both styles are legal, and they mix freely:

Def Hypot(a As Number, b As Number) As Number
    Sqr(Square(a) + Square(b))

Def Square ( Number -- Number )
    Dup *

Pedigree: Kitten’s semantics, BASIC’s keywords, Python’s layout.

1. Philosophy

• Purely functional: no variables, no assignment, no goto, no mutation — a value, once made, never changes. Let binds a name to a value; it never rebinds.
• Iteration is recursion — a function calling itself — or a combinator (Map, Fold, Filter, Each, Times). There is no mutable loop index. A for loop is a mutable index in a trenchcoat, so it does not exist here.
• Every definition compiles to a pure stack-to-stack function. The stack is the compilation target; most programs never mention it.
• Layout is structure: indentation delimits bodies and branches. No endif, no end def, no ;, no line numbers.
• Effects live at the edge: by convention, Print appears only in Main.

2. Lexical structure

• Case-insensitive — the mill ignores letter case entirely, so Map, MAP, and map are the same word. Convention: PascalCase for keywords, types, functions, and field accessors (Def, Number, MatMul, Score); camelCase for variables and parameters (xs, bestRatio). Records print back in their declared spelling.
• Self-delimiting characters: ( ) { } [ ] , — everything else splits on whitespace.
• Numbers: 42, -3, 1.5. Every number is an IEEE double — the 64-bit decimal format most languages use, exact for whole numbers up to 2⁵³.
• Strings: double-quoted, single line. Escapes: \" \\ \n \t \r.
• Comments: Rem or ' to end of line.
• Line continuation: a line whose brackets are still open continues onto the next physical line. Wrap long calls after a (, {, [, or any comma inside them. Continuation lines carry no indentation meaning, and comments and blank lines may appear mid-continuation. Any long expression can be made wrappable by parenthesizing it. A Def at the left margin always starts a new function, so a missing close bracket is reported at the line that opened it.
• Reserved characters: BASIC’s type sigils ! % # $ and the predicate suffix ? may not appear in words. Types live in declarations, not names. Predicates use the Is prefix (IsEmpty, IsEven), after Visual BASIC’s IsEmpty/IsNumeric. String words carry no sigil (Str, Mid, Left), matching Val and Asc, which never had one.
• Operators are not word characters. Words split only on whitespace, so count+1 would otherwise read as one long name rather than an addition. So an operator character — * + / < > = ^ & — mixed into a word that also carries a letter or digit is an error. The fix is a space: count + 1, x > y. The operators themselves are untouched, since none of them contains a letter or digit. Number literals are exempt, so 1E+10 is still a number. ; and \ spell nothing in the language and may not appear in a word at all; \ keeps its meaning inside a string literal. Not affected: -, which leads unary minus and stack effects (--), and ', so y and y' remain two distinct names.

3. Types

Type	Notes
Number	IEEE double
String	Immutable
Boolean	Distinct type; numbers are never truthy
List Of t	Homogeneous, immutable; literal { 1, 2, 3 }
Array Of t	Fixed-length, immutable, O(1) index; see §9
Option	Predeclared: Some(Value) | None. Absence as a value you must match; see §8.1
Result	Predeclared: Ok(Value) | Err(Why, At). Failure with a reason; see §8.1
Person, …	User records declared with Type; see §8
[ t ... -- u ]	Quotation (function value); arrow spelled as stack effect

Type variables — stand-ins for “any type” — are single lowercase letters (t, u). You never declare them; using one is enough. Annotations use BASIC’s As:

Def CountIf(xs As List Of t, p As [ t -- Boolean ]) As Number
    Length(Filter(xs, p))

Implementation status: annotations are parsed, and type checking happens at runtime — a wrong type stops the program with a line number. The mill’s weave-time linter performs stack-effect inference: net effects per Def, branch agreement, call-site depth against declared arities, and unknown words as weave errors. It warns only on what it can prove and skips what it cannot. See The linter. Full static type checking is future work.

4. Definitions

Three header forms, dispatched by shape:

Def Name(p As t, ...) As r      ' applicative body (expression syntax)
Def Name ( t ... -- u ... )     ' concatenative body, effect signature
Def Name                        ' concatenative body, undocumented effect

Applicative parameters perform an implicit Take. The body is a sequence of statements, and its final value is the result. Def Main() is the entry point.

A fourth top-level form exists: Let NAME = expr at the left margin binds a program-wide constant. All top-level Lets are evaluated once, in textual order, before Main. Each sees the earlier ones and any Def. Together they form the outermost lexical scope: visible in every body, closed over by quotations, immutable like every binding. There is no separate Const keyword — a Let that can never rebind already is one.

In a machine, a top-level Let must bind a constant. A machine has no Main, so it has no startup phase in which to evaluate an initializer. A constant needs none, because it is built once when the machine is loaded. The rule is a prohibition: the initializer contains no word calls. What it admits:

• Number and String literals, { … } list literals and type constructors, nested to any depth.
• The arithmetic and concatenation operators + - * / ^ Mod & over constant operands, folded at compile time.
• ToArray and Dim applied to constants, likewise folded. There is no array literal in the language, so an array constant is spelled ToArray({ … }).
• True and False, folded for the same reason. There is no boolean literal either — both are builtin words, so a boolean constant is spelled with them.
• An earlier constant from the same file.

Anything else is refused where it is written, naming the word that has to go. A quotation is refused by its own message: a quotation captures the environment it was made in, and a machine constant is one value shared by every program that loads the machine. A conditional is refused too, and that covers And and Or, which compile to one — naming the If the writer never typed would help nobody.

A machine constant is private to its file. A Let declares a value, not a word, and an Include gives you the words a machine declares (§13.1). So nothing crosses the boundary, and two machines may name the same constant without colliding. A machine publishes a constant with a Def that returns it. That Def then returns the same value every call:

Let unitNames = { "m", "kg", "s" }

Def Units() As List Of String
    unitNames                   ' Units() = Units() is True

That last line is the point, not a nicety. A List compares by identity — two lists are = only when they are the same list, not merely lists with the same items. So a zero-arg Def that builds { "m", "kg", "s" } hands back a different value every call, and is never equal to itself. A program’s own top-level Let is unrestricted, as above: it may call any Def.

5. Expressions (applicative bodies)

• Calls: f(a, b) desugars to a b f — arguments load left to right, then the word runs.

• Infix operators, low to high precedence: Or; And; comparisons = <> < > <= >=; + - &; * / Mod; ^. ^ is right-associative, so 2 ^ 3 ^ 2 is 512 and -n ^ 2 is -(n^2), as in classic BASIC. Not and unary - are prefix. Parentheses group.

• And and Or short-circuit in expression bodies: the right side evaluates only when it is needed. So Not IsEmpty(xs) And First(xs) > 0 is safe on an empty list. (The core’s postfix And/Or words remain strict — both operands are already on the stack by then.)

• Let Name = expr binds an immutable local for the rest of the body.

• Pipeline chaining: adjacency is stack flow. A call may consume the value of the preceding expression, and deeper-indented lines continue a statement:

  Def EvenSquareSum(n As Number) As Number
      Range(1, n)
          Filter(IsEven)
          Map(Square)
          Fold(0, +)

• Conditionals: If cond Then with indented branches; Else alone on a line at the If’s indent. If is an expression — each branch’s final value is its result. Inline alternative: Ifte(cond, t, f).

• Select Case — QBasic’s value matching, as an expression. The tested value (the scrutinee) evaluates exactly once, and the first matching clause’s block is the result. The clause forms:

  • Case expr — equality.
  • Case e1, e2, ... — any of these.
  • Case a To b — an inclusive range.
  • Case [Is] >= expr — any comparison operator.
  • Case Type(n1, ..., nk) [Where cond] — record destructuring: matches records of that Type and binds every field, in declaration order, to the given names. The names are in scope for the guard and the body.
  • Case Else — the default, last.

  With no Case Else, a non-match is a runtime error. The whole form desugars to nested Ifte over a hidden one-time binding. Note that Case Type(...) is always a pattern; to test equality against a constructed record, write Case = Type(...).

  Def Greet(p As Person) As String
      Select Case p
          Case Person(n, a) Where a < 18
              "HEY " & n
          Case Person(n, a)
              "HELLO, " & Upper(n)

  Def Grade(score As Number) As String
      Select Case score
          Case >= 90
              "A"
          Case 80 To 89
              "B"
          Case Else
              "F"

6. Function values — where the brackets went

A quotation is deferred code — code saved to run later, written in brackets in the core. In the applicative surface the brackets are rarely needed:

1. Bare names auto-quote in argument position. A name that is not a local binding is passed as a function value: Fold(xs, 0, +), Map(xs, Square), Filter(xs, IsEven). To force a bare name to evaluate instead, parenthesize it: f((g)).
2. Sections pre-load an operator’s trailing arguments: Filter(xs, >=(100)) — “≥ with 100 pre-loaded” — instead of [ 100 >= ].
3. Fn lambdas for anything genuinely inline: Filter(xs, Fn(x) => x Mod 2 = 0). Sugar for a quotation beginning with an implicit Take.
4. [ ... ] remains legal everywhere as raw core code. It is required inside concatenative bodies: without the quote marker, If’s branches would run before If did.

Call applies a function value: Call(f, acc, x) ≡ acc x f Call.

Quotations are closures. A function value remembers the variables from the place it was written (lexical scoping): Filter(xs, >=(p)) still sees p when a library word executes the quotation later. Since bindings are immutable, that capture costs one pointer.

7. Lists

{ 1, 2, 3 } builds a List Of Number. Elements are arbitrary expressions, evaluated at construction. Lists are immutable.

Primitives: IsEmpty First Rest Prepend. Library words (expressible in the language itself): Map Filter Fold Each Times Range Length Reverse Concat Call Ifte — provided as builtins for speed, and self-hostable as:

Def MySum(xs As List Of Number) As Number
    If IsEmpty(xs) Then
        0
    Else
        First(xs) + MySum(Rest(xs))

8. Records: Type

QuickBASIC’s record syntax, minus the end Type that layout makes redundant. Declared at column 0, before first use:

Type Person
    Name As String
    Age  As Number

Declaring a Type generates three things:

• A constructor word, positional or named (not mixed): Person("ANN", 34) or Person(Name = "ANN", Age = 34). Positional arity is checked at parse time.
• Accessor words for each field — words that read one field out: Name(p), Age(p). Accessors are ordinary words, so they compose with everything: Map(people, Name), Filter(people, Fn(p) => Age(p) >= 18), and in the concatenative core simply p Age. Two TYPEs may share a field name; the accessor dispatches on the record’s tag at runtime. Don’t name fields after builtins — the builtin wins. The SHODDY_LINT switch on the Toolchain page warns at weave time when a binding shadows an accessor.
• Functional update via With, returning a new record: With(p, Age = Age(p) + 1) — any number of field = value pairs.

Records are immutable. They compare structurally with = — equal when their fields are equal. They nest freely (Customer As Person), and they print as valid input: Person(Name = "ANN", Age = 34).

Sum types declare tagged alternatives on one line:

Type Shape = Circle(r) | Rect(w, h)

Each variant is a full record type — constructor, accessors, With, patterns — and Select Case dispatches on the variant:

Def Area(s As Shape) As Number
    Select Case s
        Case Circle(r)
            Pi() * r ^ 2
        Case Rect(w, h)
            w * h

A bare variant has zero fields. Construct it as None() — or bare None outside argument position — and match it with Case None (structural equality) or Case None().

8.1 The language’s own types

Two sum types are predeclared. They need no Include, and no machine owns them. Absence and failure are statements about every type, so a version you had to import would not be a replacement for NULL at all. (NULL is the “no value here” hole most languages leave open.)

Type Option = Some(Value) | None
Type Result = Ok(Value)   | Err(Why, At)

Option is the answer to NULL: absence is a value you must match, never a hole. Result is for failure that has a reason. The test that separates them: could a caller do anything different depending on why? A missing dictionary key has one possible reason and wants None. A malformed document wants the reason and the offset. At is 0 when there is no position, which reads as “absent” the same way a 1-based IndexOf returns 0 for not-found.

They generate no accessor words, and that is deliberate. A field accessor on a sum type is partial — it works on some values and dies on the rest. If Value were a word, Value(None()) would compile and then fail at runtime with “None has no field Value” — reopening the exact hole the type exists to close. Pattern binders are positional and named at the match site, so Case Some(x) already hands you the value. An accessor could only offer a way to skip the match. Select Case is the way in, and the only one.

Select Case ToBoolOpt(answer)      ' str.shoddy — no Include needed for Option
    Case Some(b)
        b
    Case None
        Print("NOT A YES OR A NO")
        False

Declaring your own type named Some, None, Ok or Err is a duplicate-definition error, as it would be for any name already taken.

Patterns nest. A sub-pattern may be a binder name or another Type(...) pattern, to any depth. _ is an ordinary binder used by convention for ignored fields:

Select Case o
    Case Order(Person(n, _), items, total) Where total > 100
        n & " (BIG SPENDER)"

9. Arrays

List is the inductive type — cheap First/Rest/Prepend, made for walking front to back by recursion. Array is the indexed type: fixed length, immutable, Nth in O(1) — constant time, however long the array — and a functional SetNth that returns a new array. Use lists to recurse and arrays to index; matrices are arrays of arrays.

Let a = ToArray(Range(1, 5))    ' Array(1, 2, 3, 4, 5)
Nth(a, 3)                       ' 3, in o(1)
SetNth(a, 3, 99)                ' Array(1, 2, 99, 4, 5) — original untouched
Dim(3, 0)                       ' Array(0, 0, 0) — basic's keyword, reclaimed

Map Filter Fold Each Length IsEmpty First Nth SetNth Reverse Concat Sort are polymorphic over both kinds, and they preserve the input’s kind — Map over an array yields an array. ToArray/ToList convert. Rest/Prepend stay list-only by design: on an array they would hide an O(n) copy, a cost that grows with the whole array.

The same rule decides which kind a constant should be (§4). A table consulted by index is an Array; a table consumed by structural recursion is a List. Both may be held by a machine’s top-level Let — an array constant is written ToArray({ … }), which is folded at compile time.

10. Word reference

Arithmetic

+ - * / Mod ^ Negate Abs Min Max Sqr Floor Ceil Round — owned and documented by math.

Math

Sin Cos Tan Atn Atn2 Asin Acos Tanh Exp Log Log10 Pi Sgn Fix Wrap (radians; Log is natural log; Tanh is the hyperbolic tangent, saturating to ±1; Wrap is floored modulo) — owned and documented by math.

Special functions

Erf GammaP BetaI — the error function and the regularized incomplete gamma and beta functions. These are the native-precision primitives under stats.shoddy’s probability curves — owned and documented by stats.

Random

Rnd — uniform in [0, 1); impure, like Print. Seed(n) makes it reproducible. Rnd is owned and documented by random; Seed by math, since random is seedless by construction

Comparison

= <> < > <= >= (numbers or strings) → Boolean

Logic

And Or Not True False (strictly boolean)

Strings

& Len Str Val Left Right Mid Chr Asc Upper Lower Instr InstrFrom Codes FromCodes CodeAt. Mid is 1-based: Mid("HELLO", 2, 3) → "ELL". Instr(s, sub) is the 1-based position of SUB in S, 0 if absent. InstrFrom(s, sub, from) is the same from a position, answering 0 for a from past the end. Codes(s) is an Array Of Number of every UTF-16 code unit — the 16-bit pieces a string is stored as — and FromCodes is its exact inverse, NUL included, which Chr cannot build. CodeAt(s, k) refuses a position past the end, where Mid trims. It is how a character is read, and Asc(Mid(s, k, 1)) is the trap it replaces. — owned and documented by str.

Lists & arrays

IsEmpty First Nth SetNth Map Filter Fold Each Times Range Length Reverse Concat Sort (polymorphic; Sort ascending over all-numbers or all-strings); Rest Prepend (lists only); Dim ToArray ToList (arrays) — owned and documented by seq.

Records

Type declarations; per-type constructor and accessor words; With for functional update

Functions

Call Ifte — owned and documented by lineshaft.

I/O

Print; Input(prompt) prints the prompt and reads a line as a String (numbers via Val). InputLine(prompt) does the same but also answers whether the read hit the end of the input, as a 2-element Array [atEof, text]: element 1 a Boolean, True only at genuine end-of-input; element 2 the line, empty at the end. Input collapses end-of-input and a blank line into "". So a program reading a redirected script can either reprompt on a blank line or stop at the end — never both — and InputLine is how you get both. It is a flat Array rather than a record because a builtin cannot reach a Type; lifting it into a sum type is the Shoddy caller’s job. InKey() reads one pending keystroke without blocking or echoing — "" when none is pending. Arrow keys and PF1–4 arrive as their VT100 application-mode escape sequences. — owned and documented by terminal.

Files (text, whole-file)

No handles — a text file is read or written whole, and paths resolve against the working directory. The words: ReadFile(path) → String (a missing file stops the program); TryReadFile(path) → Result, the same read with the failure reported rather than fatal; WriteFile(path, s) (overwrite); TryWriteFile(path, s) → Boolean, the same write with the failure reported rather than fatal; AppendFile(path, s); FileExists(path) → Boolean; DeleteFile(path) (a missing file stops the program); TryDeleteFile(path) → Boolean — True if the file went, False if it was not there or could not be removed. Shoddy has no catchable errors, so the Try words are the only way to ask "can this path be read?", "can this path be written?" or "did this file go?". FileExists cannot answer any of them: a directory reports False, an existing file that cannot be opened reports True, and a file that exists can still be locked when a delete lands. — owned and documented by file.

TryReadFile answers the language’s own Result (§8.1) rather than a Boolean. Unlike TryWriteFile, it has a payload to carry on success, and reasons worth telling apart on failure: Ok(text), or Err(why, 0) where why is CANNOT READ 'path' (…) ending in one of NO SUCH FILE, IS A DIRECTORY, ACCESS DENIED or UNREADABLE. The phrase is a closed set of Shoddy’s own, never the host platform’s exception text, which varies by OS and language setting. At is 0: a failure to open the file has no position in it.

Select Case TryReadFile(path)
    Case Ok(text)
        text
    Case Err(why, _)
        Print(why)
        ""

Files (binary, random-access)

Classic BASIC record files. BOpen(path) → a handle — a Number that stands for the open file — opening read/write and creating if absent, with up to 16 open at once. TryBOpen(path) → Result: Ok(handle), or Err(why, 0) with why = CANNOT OPEN 'path' (…) from the same closed set TryReadFile uses, plus TOO MANY OPEN FILES. It differs from BOpen twice over, and both differences are the point: the failure is reported rather than fatal, and it opens an existing file only. BOpen’s open-or-create means a failed read leaves an empty file behind, so asking whether a binary file is there damages the answer. And since nothing can learn a file’s size or its leading bytes without opening it, TryBOpen is the only way to test a binary read before committing to it. BClose(h); Seek(h, pos) — byte positions are 1-based; BPos(h) / BSize(h). Typed transfer, each advancing the position: PutNum/GetNum (8-byte IEEE double), PutBool/GetBool (1 byte), and PutStr(h, s, Len) / GetStr(h, Len) — fixed-length zero-padded fields. PutStr writes exactly Len bytes; an over-length string stops the program rather than silently truncating. GetStr reads exactly Len and strips the padding. Fixed field sizes make record layouts computable: a Name(12) + Score(8) record is 20 bytes, so record K starts at 1 + (k-1)*20. Reading past the end of the file stops the program. All I/O words are effectful — by convention, Main’s side of the program only. — owned and documented by recio.

TCP/IP sockets (gated)

A network capability, off unless the mill runs with --allow-net (which sets SHODDY_ALLOW_NET, so a standalone woven exe honors the same switch). The first socket word otherwise stops the program. Two words are the exception, and they exist so guarded code can reach the family at all. NetAllowed() → Boolean answers whether the capability is on, and is not itself gated: the question has to stay askable when the answer is no, or nothing could tell "no network" from "no answer" without ending the run. TryTcpConnect(host, port) → Result is TCPConnect with all three of its failure modes reported instead: Ok(handle), or Err(why, 0) where why is CANNOT REACH 'host:port' (…) ending in one of NETWORK IS DISABLED, TOO MANY OPEN SOCKETS, TIMED OUT or NO SUCH HOST OR REFUSED — a closed set of Shoddy’s own, never the platform’s socket text. TryTcpRequest(host, port, secure, msg) → Result guards the whole conversation rather than a step of it: connect, optionally secure, send, read to the end of the reply, close, answering Ok(reply) or the same shape of Err. It exists because guarding the steps is not enough. TCPSend and TCPRecv fail eight ways between them on ordinary network faults, so a caller composing guarded parts would have to close the socket on each of a dozen error paths — and would leak it on the one missed. Here the socket cannot outlive the word. It is also the only network read that cannot hang: it is bounded by a deadline, where a poll-until-closed loop never returns against a peer that keeps the connection open. Handles are Numbers, like file handles (up to 16 open); payloads are Strings, one byte per character (the Latin-1 convention). The family: TCPConnect(host, port) → handle (bounded 10-second handshake; stops the program if unreachable); TCPListen(host, port) → handle, binding an IP literal ("127.0.0.1" loopback, "0.0.0.0" any); TCPAccept(h) → a connection handle, or 0 when none is waiting; TCPSend(h, s); TCPRecv(h, max) → up to max bytes, "" when nothing is pending or the peer has closed; TCPEof(h) → Boolean, telling those two apart; TCPPoll(h) → Boolean, whether Recv/Accept would find something now; TCPPeer(h) → the remote "ip:port"; TCPClose(h); TCPSecure(h, host) upgrades a connected socket to TLS — encrypted transport — in place, the host name driving both the request and the certificate check (a failed handshake closes the handle). Every readiness word on a plain socket is non-blocking: a program polls, optionally around Sleep, so a socket never freezes a scribbler window or a debug session. A secured handle is the deliberate exception. There, TCPRecv blocks until data, end-of-stream or a 30-second timeout and returns "" only at the end; TCPEof reads a flag rather than polling; and TCPPoll refuses, because once TLS records wrap the stream a TCP-level poll cannot answer honestly about the decrypted data. TLS is for request/response at the edges; the polling contract is for game loops on plain sockets. net.shoddy layers Connect/RecvAll/Request/HttpGet/Listen/Serve1 on top. — owned and documented by net.

Command line

Args() → List Of String, the program’s arguments. Core, and also documented in terminal — but not terminal-exclusive: a headless service or a GUI-launched program has arguments too.

Time

Ticks() → monotonic milliseconds (fractional) for measuring; Sleep(ms) yields the thread; Clock() → a 7-element Array of wall-clock now: year, month, day, hour, minute, second, millisecond. — owned and documented by clock.

Graphics (the scribbler)

ScribblerOpen(w, h) → handle. It requires the window backend — mill run/mill dap; woven output run via bare dotnet stops the program. ScribblerClose ScribblerTitle ScribblerPixel ScribblerFill ScribblerText ScribblerGetPixel ScribblerWidth ScribblerHeight ScribblerBlit ScribblerSetInterval ScribblerPoll ScribblerWait. Every word leaves exactly one value — mutators return the scribbler, so Let sc = ... chains read functionally even though the pixel buffer changes in place. Nothing shows until ScribblerBlit. ScribblerPoll/ScribblerWait → a raw 8-element event array (kind 0 = none; Wait blocks at zero CPU, and stops the program headless — nothing would ever wake it); scribbler.shoddy decodes it to a ScribblerEvent. ScribblerSetInterval(sc, ms) asks for tick events (0 = off). ScribblerSave(sc, path) writes the buffer to a PNG — eight-bit truecolour, alpha dropped, no window consulted, so it works headless and under --no-window. ScribblerPlace(sc, x, y) asks for the window’s top-left corner in desktop pixels; a window manager may ignore it, and nothing reads it back.

Three words reach the same windows by SLOT NUMBER, and they exist for one caller. A Scribbler is its own kind of value, so unlike a file handle it cannot be carried by a number — and a number is what a reckoner seed needs, since a resource held in reckoner’s named table is found again by an integer the binding carries. TryScribblerOpen(w, h) → Result is ScribblerOpen with both of its failure modes reported rather than fatal — no window backend, and a size below 1×1 — answering Ok(slot) rather than the window itself. ScribblerOf(n) → the window that slot names. ScribblerShut(n) → Boolean closes it and frees the slot, answering False for one already let go, so that closing twice cannot end a run. An ordinary program takes the window from ScribblerOpen and never sees a slot. — owned and documented by scribbler.

Sound (the buzzer)

Sound(freq, ms) NoteOn(ch, freq) NoteOff(ch) SoundQueue(ch, freq, ms) SoundStop(ch) SoundGain(ch, vol) SoundWave(ch, wave) — channels 1–8, and three note-lifetime models: fire-and-forget pool, held until released, and queued back-to-back sample-accurately. For SoundQueue, freq 0 is a rest, and queueing more than five minutes ahead stops the program; SoundQueued(ch) → the milliseconds already queued ahead, which is the only way to see that cap coming. SoundWave picks a channel’s timbre, sticky like gain: 0 square (default), 1 triangle, 2 sine. A held note re-voices in place; the anonymous pool is square only. Sound never blocks and never fails the program: audible under mill run/mill dap, a silent no-op headless. But bad arguments — channel 0, a negative duration, wave 3 — raise even in silence. — owned and documented by buzzer.

Errors

Error ( s -- ) stops the program with the message and line number; Assert(cond, msg) stops it unless COND is True — owned and documented by lineshaft.

Stack (concatenative bodies)

Dup Drop Swap Over Rot Nip Tuck Depth

11. Desugaring summary

Surface	Core
f(a, b)	a b f
a + b	a b +
xs Filter(p)	xs p Filter
Let x = e	e Take x
Def f(a As t, ...) As r	Def f + implicit Take
bare Name as argument	[ Name ]
>=(100)	[ 100 >= ]
Fn(x) => body	[ Take x body ]
{ 1, 2, 3 }	list construction
If c Then a Else b	c [ a ] [ b ] Ifte
Call(f, acc, x)	acc x f Call
Person(Name = n, Age = a)	n a Person (declaration order)
Age(p)	p Age

12. Tail calls and errors

Tail recursion is the language’s loop. When a function’s last act is calling itself, the mill compiles that call into a jump, so the Fact-with-accumulator shape runs in constant stack space. Mutual recursion — two functions calling each other — still consumes stack. Runtime errors — stack underflow, type mismatch, unknown word, division by zero — stop the program with a message and a source line number.

13. Include and the standard library

Include "FILE.SHODDY" at the left margin splices another source file in at that point, once per file however often it is included. Resolution tries three places, in order:

1. Relative to the including file.
2. The directory named by the SHODDYLIB environment variable — a named setting the operating system passes to every program.
3. The machine library shipped with the mill that is running: machines/ beside the executable, then one level up, beside its bin/.

The fallbacks are what let a program keep a bare Include "seq.shoddy" wherever it is copied. A repo’s bin/mill finds machines/ at the root, and the mill bundled in the VS Code extension finds the one staged beside it — neither needs anything set. SHODDYLIB stays the explicit override that pins a checkout to its own machines. A file found in a machine library is a machine, and is always used compiled: the mill links Shoddy.Machines.Seq.dll beside the source, building it first if it is missing or stale. A file found beside the includer — one of your own program’s files — is spliced. Declarations must precede use, so libraries go at the top.

13.1 Namespaces

There are two kinds of Include, and the difference is one sentence: a machine is a boundary, and a program’s own files are one program. Including one of your own source files splices it: every Def, Type, variant, and field accessor lands in one flat table alongside the builtins. That is what lets a mill split itself across a dozen files without ceremony. Including a machine gives you the words that machine declares, and not the words it includes in turn. Include "stats.shoddy" does not hand you seq’s ZipWith merely because stats uses it. Name what you use. The refusal says which Include to add, and the dependency is compiled and linked either way — only the naming is scoped.

Within one file, then, every visible declaration is in one flat table. Include "FILE.SHODDY" As NAME pastes NAME onto the front of everything that file declares. A file included As Msg declaring CaveNearby declares MsgCaveNearby — the same name a hand-written prefix would have produced, so existing call sites keep working.

Qualification is never required at the use site. A bare word resolves while its meaning is unambiguous, in this order: first the namespace the use site is itself written in (a file’s own names come first, so qualifying two files that share a helper name breaks neither), then an exact declaration, then a unique namespaced name. Only a genuine collision between two namespaces forces you to choose, and the error names both candidates. (This chooses which declaration a name refers to. What a word means when local bindings, Defs, builtins, and accessors all compete is the separate chain described on the Toolchain page.)

To choose, write NAME In NAMESPACE — Hints In Tbl(), Died In Core (m) in a pattern, Anchor In Vocab (k, t) for a constructor. It collapses to the single word TblHints, so both spellings mean exactly one thing.

Three details are worth knowing:

• An As namespaces the surface of the file you named, and nothing further — the words that file declares, not the words it in turn includes. So Include "net.shoddy" As Sock spells net’s own Connect as SockConnect, and leaves Join — which net gets from str.shoddy — spelled Join. Namespaces therefore do not compose through a chain of includes. A name never depends on who included the includer, and a file’s spelling never depends on its dependencies’ include lists — adding an include to str cannot change what As Sock spells.
• Only the accessor word is namespaced, not the field’s identity. With(g, Dflag = 3) still names the field bare, and a namespaced accessor is reachable as Key In Vocab (a) even where a local named key would shadow the bare spelling.
• A machine include takes As too, which is what lets two machines exporting the same word be used in one program. One pair in the library still does: net.shoddy and turtle.shoddy both export Close. Include both and you name one of them — Include "net.shoddy" As Sock, whose words read naturally prefixed — and leave turtle’s bare. Include only one and there is nothing to disambiguate, so you need no As at all. A machine’s own dependencies are not part of your program’s names, so they cannot collide with anything either.

Two further guards, independent of namespaces. Declaring a name twice is an error that names the earlier file and line. And a Def whose name is a builtin is refused, because a Def outranks a builtin everywhere in the program. Write Redef in place of Def when the override is deliberate.

The standard library is written in Shoddy itself:

• seq.shoddy — the Fold/Map usual suspects, structure only: Any All CountIf Contains IndexOf IndexOpt Taken DropN Append Last Flatten Zip ZipWith, plus Type Pair (Fst/Snd). IndexOpt answers the not-found case with the language’s Option; IndexOf keeps its 0 sentinel — a special value standing for “not found” — because the tree already reads it. Aggregation lives in stats.shoddy; sorting is the Sort builtin.
• matrix.shoddy — Type Matrix over a flat row-major array, meaning the rows are stored one after another in a single array (O(1) MatGet, dimension-checked ops via Error): Mat MatFill Ident MatFromRows MatGet MatSet MatRow MatCol Dot VAdd VSub VMul VScale Outer MatMul MatAdd MatSub MatScale Transp MatVec MatShow. VMul is elementwise; Outer is the outer product. The algorithms over the type — determinants, inverses, systems, rank, factorisations, eigenvalues — are lin.shoddy; this machine owns the structure and its arithmetic. Includes seq.shoddy.
• lin.shoddy — linear algebra over matrix.shoddy’s Matrix. Measures (LinTrace LinNorm LinMaxAbs LinIsSym LinIsSquare), vectors (LinVNorm LinVUnit LinCross), building (LinBuild LinSwapRows LinScaleRow LinScaleCol LinAug LinCols), elimination with partial pivoting (LinRef LinRref LinRank), LinDet LinInv LinSolve LinPow LinMinor LinCofactor LinAdj, the factorisations (LinLuOf → Type LinLu with LFactor UFactor Perm PSign, LinQrOf → Type LinQr, LinChol), and the eigenproblem (LinCharPoly by Faddeev-LeVerrier, coefficients highest power first; LinEigVals; LinEigSym by cyclic Jacobi → Type LinEigen). LinEigVals finds the real eigenvalues only, by bracketing sign changes, so an answer shorter than Rows(m) is itself information; LinEigSym is complete for a symmetric matrix. Every solver checks its precondition and stops rather than returning a plausible wrong answer. A program normally includes matrix alongside it, since it must name Matrix. Includes matrix, eng and seq.
• alg.shoddy — symbolic algebra, where the values are formulae rather than numbers, over Type AlgEx = AlgNum(AlgNumer, AlgDenom) | AlgVar | AlgSum | AlgProd | AlgPow | AlgCall. No subtraction and no division variant: a - b is a sum with a term times −1, and a / b a product with a factor to the −1. So every walker has six cases, and the simplifier never reasons about a - b + b; AlgShow reconstructs both on the way out. Numbers are exact rationals — fractions kept as numerator and denominator — always normalised by AlgRat: 1/3 + 1/6 is exactly 1/2, which is what lets AlgFactor find rational roots and AlgMaclaurin return 1/120. A recursive-descent parser (AlgParse stops the program on bad input, AlgRead is total and returns Result) and a minimally-parenthesising printer round-trip against each other. A capped-fixpoint simplifier works over a documented total order (AlgCompare, AlgEqual — never =). Total differentiation including the general power rule; AlgExpand AlgFactor AlgPolyCoeffs AlgPolyDivide AlgPartFrac AlgTogether; AlgLimit AlgLimitInf AlgInteg AlgIntegDef AlgIntegRules AlgSolve AlgDeSolve AlgTaylor AlgMaclaurin; and AlgToFn, which compiles an expression to a quotation, so every numeric word in eng accepts a user-typed formula. Neither machine includes the other, because a quotation is a builtin type. The partial words return the language’s Result, and Err there usually means “outside the implemented rules” rather than a fault: Err("IRREDUCIBLE OVER THE RATIONALS", 0) is a fact about the polynomial. Bounded and honest about it: table-driven integration, univariate rational factorisation, substitution-plus-L’Hôpital limits, distinct linear factors in partial fractions, first-order ODEs. Includes seq, sinq and str.
• sinq.shoddy — querying a sequence, and only what the rest of the library could not already say. Ordering by a key with composable comparers: Compare ByKey Descending ThenBy OrderWith OrderBy OrderByDesc, over a stable merge sort — equal items keep their order, which is what makes ThenBy mean anything. The item with the smallest or largest key, rather than the smallest number: MinBy MaxBy over MinByOpt MaxByOpt. GroupBy → Type Group (GKey/GItems), groups in first-appearance order and items in source order. JoinOn (inner) and GroupJoinOn (left outer; the name Join is str’s). Distinct DistinctBy Union Intersect Except. SelectMany Thru Descendants Offspring for a record graph that holds itself — cycles are unconstructible, so none is checked for. OptMap OptBind OptOr ThruOpt Choose where a hop can fail, and TakeWhile SkipWhile Chunk FirstOpt LastOpt SingleOpt FindOpt. Re-declares nothing: aggregation stays in stats, the big four stay builtins. Written to index arrays rather than walk lists with Rest, and self-tail-recursively throughout, because Rest copies and only self-tail-recursion becomes a loop. Pure. Includes seq.shoddy.
• str.shoddy — Split Join Trim Replace StartsWith EndsWith StrRep, built on the Instr/InstrFrom/Left/Right/Mid builtins; the fixed-width formatters PadLeft PadRight PadZero ToFixed CommaGroup Commas; and the boolean conversion trio IsBool ToBool ToBoolOr over the primitive ToBoolOpt, mirroring the IsNumeric/Val/ValOr builtins for numbers. (ToBool and ToBoolOr were Bool and BoolOr before v1.7.0.)
• regex.shoddy — regular expressions — text-matching patterns — as a compiled value. RxRead parses a pattern to a tree, compiles it to an instruction program, and answers Ok(prog) or Err(why, at); every match word takes the program, never a string. The engine is a Pike VM — a design that runs all possible matches in step rather than trying one and backing up — so it never backtracks, and cost is bounded by pattern size times subject length: (a|a)*b against thirty as returns at once. Nothing in the file stops the program: a malformed pattern is an Err, an absent match or an unset group a None(), and there is not one call to Error — which is why the errors page has no row for it. RxTest RxFind RxFindFrom RxMatchAt RxFindAll RxGroup RxGroupOr RxCount RxSource RxDisasm RxReplace RxReplaceFirst RxReplaceWith RxSplit RxQuote, with RxNoOpts/RxFoldOpts for ASCII folding, dot-all and multiline. The price of the guarantee, refused by name at its offset: no backreferences, no lookaround, no atomic or possessive forms, no named groups, no scoped inline flags. The domain is UTF-16 code units classed as ASCII, so a NUL is an ordinary literal that FromCodes can build and \0 matches; semantics are leftmost-first (Perl), not leftmost-longest (POSIX). A counted repetition compiles by duplication, so RxMaxCode() caps the program at 2000 instructions and refuses past it at parse time. Includes nothing: every word it needs is a builtin.
• bool.shoddy — the binary layer, and the answer to there being no bitwise builtins: And/Or/Not are Boolean operators only, so every bit operation here is Mod and 2 ^ n written once and named. Bases and rendering (BoolInBase BoolFromBase BoolFromBaseOr BoolHex BoolBinS BoolOctS BoolHexW BoolBinW BoolGrouped BoolCard BoolCardWith); bit operations (BoolBitAnd BoolBitOr BoolBitXor BoolBitNot BoolBitNand BoolBitNor BoolBitXnor BoolShl BoolShr BoolShrA BoolRotl BoolRotr); masks, fields and inspection (BoolMask BoolMaskFrom BoolTest BoolTestAny BoolSet BoolClear BoolToggle BoolGetField BoolSetField BoolDecode BoolBitAt BoolSetBit BoolPopCount BoolLowBit BoolHighBit BoolLog2Floor BoolLeadZeros BoolReverse BoolBitList BoolFromBitList BoolIsPow2 BoolNextPow2, over Type BoolField); two’s complement — the standard binary spelling of negative numbers (BoolSigned BoolUnsigned BoolSignExtend BoolNeg BoolAddW BoolSubW BoolMulW BoolCarries BoolOverflows); the codes (BoolGray BoolFromGray BoolParity BoolParityBit BoolHamming BoolBcd BoolFromBcd BoolFromBcdOr); the nine gates over Boolean (BoolAnd BoolOr BoolNot BoolNand BoolNor BoolXor BoolXnor BoolImplies BoolIff); truth tables over a quotation, never a parsed string (BoolRowInputs BoolRowIndex BoolTruthTable BoolMinterms BoolMaxterms BoolFromMinterms BoolIsTautology BoolIsContradiction BoolEquiv BoolTableText, over Type BoolRow); and Quine–McCluskey minimisation (BoolPrimeImplicants BoolMinimise BoolMinimiseWith BoolTermCovers BoolTermMinterms BoolTermText BoolTermSumText BoolSopText BoolPosText, over Type BoolTerm). The domain is checked, never masked: every value is a non-negative whole number below 2⁵³, and every word errors naming itself on anything else, since a silently masked input is a plausible answer with the bug upstream. Widths run 1 to 53, because a 54-bit word cannot represent its own top bit. Exactly three words are width-free (BoolBitAnd, BoolBitOr, BoolBitXor), and variable 1 is the most significant bit of a row index. Reading external text answers the language’s Result (BoolFromBase, BoolFromBcd), and an absent bit answers Option (BoolLowBit, BoolHighBit) — no −1 sentinel anywhere. BoolMaxVars() = 12 is a hard refusal, since a 2¹⁶-row table is not a slow answer but a hang. Includes seq, sinq and str.
• money.shoddy — exact currency as Type Money over whole cents. Whole cents stay exact past $90 trillion in a double, so no DECIMAL type is needed: Dollars MoneyVal MoneyAdd MoneySub MoneyMul (explicit rounding) MoneySum MoneyLt MoneySplit (penny-preserving allocation) MoneyFmt. Includes str.
• file.shoddy — line-oriented text files over the whole-file builtins: ReadLines (normalizes \r\n, drops the trailing newline), WriteLines, AppendLine. Includes str.shoddy.
• fin.shoddy — finance: time value of money (FinPv FinFv FinPmt FinNper and the annuities), loans and amortisation (FinBalance FinAmortAt FinSchedule FinExtraPayoff), appraisal (FinNpv FinNpvOf FinIrr FinMirr FinPayback), small business, the four depreciation methods, the day-count bases (FinDays360 FinDateDiff FinYearFrac, over julian.shoddy’s JulDate — the calendar this machine once carried as a stated stand-in) and bonds (FinBondPrice FinYtm FinMdur). Rates are decimal fractions per period, and everything is a plain Number in whole currency units. money.shoddy is deliberately not used: Money has no division, so half of this machine could not be written in it. The statistics a finance report wants are here too, with a Fin prefix, so a caller never has to know which machine a word lives in. Includes seq, stats, math, str and julian.
• recio.shoddy — record-oriented binary I/O: give it a record size and a reader/writer function, and it does the offset arithmetic. RecPos RecSeek RecCount GetRec PutRec AppendRec AllRecs (records numbered from 1).
• dict.shoddy — dictionaries as association lists — a plain list of key/value pairs (List Of Pair). Keys compare with =, so any equatable value works. DictPut DictGet DictGetOr DictHas DictDel DictKeys DictVals. Pure; a hashed implementation could replace it behind the same words. Includes seq.
• stats.shoddy — statistics, pure Shoddy over the Erf/GammaP/BetaI and Sort builtins. Descriptive: Sum Product Maximum Minimum Mean (Average is an alias) WeightedMean GeoMean HarmonicMean Median Quantile Percentile Iqr RangeOf Var VarP StdDev StdDevP StdErr Mad Skewness Kurtosis ZScore ZScores Outliers OutliersZ Freq RelFreq Modes Ecdf Cov Correl Spearman LinFit (→ Fit). Distributions: NormPdf NormCdf Chi2Cdf TCdf FCdf NormInv TInv. Inference (all → TestResult(Stat, Df, PVal), two-sided): TTest1 TTest2 TTestPaired ZTest1 Anova ChiSqGof ChiSqTest TwoPropZTest, plus MeanCI PropCI (→ Pair) and CohenD. Sample forms divide by n−1; quantiles interpolate (R type 7). Includes seq.shoddy and dict.shoddy.
• isam.shoddy — indexed-sequential files: fixed-length records with a 1-byte tombstone flag per slot — the marker that says a slot’s record was deleted — plus a key→slot index kept on disk as a B+tree, a self-balancing lookup structure, in a companion file (path & ".idx": a header with the root page, live count, and free-list head; the free list threads through dead slots’ payload bytes). Opening reads the header — O(1), no scan — and falls back to a one-time rebuild scan only when the index file is missing. Index entries hold slot numbers, and keys are re-derived through KeyOf, so Number and String keys both work with no width limit. Mutating words still return the handle (unchanged — it carries only the two file handles and your functions). Keys come from a user KeyOf function; deletes free slots for reuse. IsamOpen IsamClose IsamInsert IsamUpdate IsamDelete IsamGet IsamGetOr IsamHas IsamCount IsamAll IsamRange IsamFirst IsamLast IsamNext IsamPrev. Sequential access is cursorless (key-order navigation). No crash safety or concurrency; one live handle at a time.
• json.shoddy — JSON to RFC 8259 (the JSON standard), both directions. Type Json = JNull | JBool | JNum | JStr | JArr | JObj, where an object’s members are a List Of Pair — dict.shoddy’s association list exactly, so JGet/JPut delegate rather than duplicate. Reading is a guard pair: JsonParse stops the program on bad input; JsonRead is total and returns JOk or JErr(why, at) with the 1-based offset, which is how a program survives input it did not write. The character scanners are self-tail-recursive, so they compile to loops and a long document costs no stack. Value/array/object recursion is mutual, and therefore bounded by a depth limit — 200 by default. Numbers are validated against the JSON grammar before Val sees them, since Val is strtod and far laxer. JsonRead JsonReadDepth JsonParse JsonLoad JsonText JsonPretty JsonSave JsonEscape JsonCanonical JGet JGetOr JHas JNth JPath JPathOr JKeys JCount JEqual IsJNull JStrOr JNumOr JBoolOr JPut JDel JNumList JStrList IsFinite. Known limits: Str gives ten significant digits, so arbitrary doubles do not round-trip bit-exactly; a string cannot carry NUL, since Chr(0) is the empty string, so is a JErr; duplicate keys collapse with the last value winning; and documents compare with JEqual, not =, because a List compares by identity. Includes seq, dict, sinq and str.
• xml.shoddy — XML 1.0, well-formed, both directions. Type Xml = XDocument | XElem | XText | XComment | XPI | XCData | XDoctype, where an element’s attributes are a List Of Pair — dict’s association list — so XAttr/XPutAttr are DictGet/DictPut in a hat. Reading returns the whole document, prolog and all, so a round trip keeps the declaration, the comments and the doctype; XRoot reaches the root element. XmlRead is total (XOk/XErr with a 1-based offset); XmlParse stops the program on bad input. The five predefined entities and numeric references only. The doctype internal subset is deliberately not read, which is also what makes the billion-laughs expansion attack impossible. Numeric references decode to their UTF-8 bytes, because ReadFile is one byte to one character and a literal character in the file already is those bytes. XmlPretty refuses to re-indent mixed content or anything holding CDATA. Namespaces are carried literally, not resolved. Includes seq, dict, sinq and str.
• html.shoddy — HTML, forgivingly, built on xml and reusing its tree outright: a parsed page IS an Xml, so XFind, XPath, XTextOf and XEqual work on it unchanged. Handles case folding, the fourteen void elements, raw-text script and style, quoted/unquoted/valueless attributes, end tags implied by a sibling or a closing parent, and a stray end tag — which is dropped rather than allowed to close its ancestors, and the reader threads the open-element stack to do it. About eighty named character references plus numeric ones; an unknown name is left standing as text rather than being an error. Not the HTML5 tree-construction algorithm: no adoption agency, no foster parenting, no invented tbody. Includes seq, str, dict and xml.
• csv.shoddy — CSV to RFC 4180 (the CSV standard), both directions. A document is the plain thing it looks like — a List Of List Of String — so seq works on it unchanged. The point of the machine is everything Split(line, ",") cannot do: a cell that CONTAINS the separator, a quote or a line break. Quoting is the whole of RFC 4180’s escaping. A quoted cell may hold anything, a doubled "" inside one is a single literal quote, and there is no backslash anywhere in it. The reader is total — CsvRead → CsvOk or CsvErr(why, at) with a 1-based offset — and CsvParse is the half that stops the program. Dialects rather than flags, every reader and writer having an -As twin: CsvComma CsvRfc (CRLF) CsvTabs CsvSemis CsvSepBy, with combinators CsvTrimming (drop spaces around UNQUOTED cells only) and CsvCommented stacking, and CsvNumeric the repo’s own .dat spelling. Ragged rows are not an error, because files in the wild are ragged — CsvWidth CsvIsRect CsvRect CsvDropBlanks CsvFlip ask and repair. Compare with CsvEqual, never =: a List is a quotation and compares by identity. Above the rows sit two optional layers. A sheet reads the first record as a header, after which columns have names (CsvSheetLoad CsvHeads CsvBody CsvGet/CsvGetOr CsvNum/CsvNumOr CsvColumn CsvColumnNums CsvWhere), and CsvPairs zips a row with that header into precisely dict’s association list — the same arrangement json makes for object members. And a Type: hand CsvRecs/CsvFromRecs the two functions that know your record, and the machine never learns it. Writing quotes minimally, plus one rule RFC 4180 does not ask for: a leading or trailing space also forces quotes, so a round trip stays exact under CsvTrimming. A blank line is a record of one empty cell, as the RFC says. The single line ending at the end of a file is the last record’s terminator, and does not start another. Includes seq, dict and str.shoddy.
• shaker.shoddy — reversible obfuscation — scrambling that can be unscrambled with the key: a four-round Feistel network (a classic scrambling recipe) over a List Of Number, keyed by another, with a Fletcher-style checksum appended so tampering is detectable. Values are field elements — whole numbers in 0 .. ShakeModulus() - 1 — and anything else is refused rather than mangled. The modulus is 67108859, the largest prime below 2²⁶. The round function squares its argument, and a double holds integers exactly only to 2⁵³, so a larger modulus overflows into a region where a product has no fractional part and the round function silently returns 0 forever. Decryption is a guard pair: ShakeDecrypt stops the program on a bad tag, ShakeDecryptOr hands back a default, ShakeVerify asks on its own. ShakeEncrypt ShakeDecrypt ShakeDecryptOr ShakeVerify ShakeChecksum ShakeModulus ShakeRounds ShakeWrap ShakeIsField ShakeAllField. An obfuscation layer, not a cryptosystem: too few rounds, a key schedule that is a bare rotation, and a checksum that catches accidents rather than forgeries. Includes seq.shoddy.
• math.shoddy — the derived math layer over the numeric builtins: E Tau Rad Deg Angle Frac RoundTo Clamp Lerp InvLerp Remap Smoothstep Hypot Dist Log2 LogBase, plus game-flavored randomness RandRange RandInt Pick Chance. Pure except the random words.
• eng.shoddy — engineering mathematics, and a closed Eng* surface: no stats, math, str or seq name appears in a signature. Angles are radians at every boundary (there is no degree mode, because a mode is state), and polynomial coefficients are highest power first. Trigonometry the runtime does not supply, and all twelve hyperbolics. Type EngComplex with EngCAdd EngCMul EngCDiv EngCExp EngCLog EngCSqrt EngCPow EngCShow — compared with EngCNear, never =. Numeric calculus over quotations (EngDeriv EngDeriv2 EngIntegrate EngSumOf EngProdOf); root-finding and optimisation (EngZeroOf, which checks its bracket contains a sign change before descending, EngNewtonOf EngMinOf EngMaxOf); polynomial arithmetic over coefficient lists (EngPolyEval EngPolyAdd EngPolyMul EngPolyDiv EngPolyDeriv EngPolyIntegral EngQuadRoots EngCubicReal); number theory (EngGcd EngLcm EngModPow EngModInv EngIsPrime EngFactorize EngTotient); combinatorics and the gamma family (EngFact EngComb EngPerm EngGammaLn EngGamma EngBeta); the discrete distributions; descriptive statistics wrapped so the caller never leaves; numeric sequences; unit conversion where a unit is a record carrying its quantity, so a mismatched conversion stops the program rather than happening; the CODATA constants (the standard published values of the physical constants) as Type EngConst; and presentation (EngSigFig EngSci EngMetric EngCommas). Ceilings, each stated where it bites: 2⁵³ for the whole-number words, |x| > 710 for EngSinh/EngCosh/EngGamma, and about eight digits from EngDeriv. Includes stats, math, seq and str.
• geo.shoddy — the Earth as arithmetic, and a closed Geo* surface. Degrees at every boundary — a deliberate divergence from eng, because a coordinate is written in degrees everywhere, so a radians surface would put a conversion at every call site. Metres for every distance and no unit mode; bearings 0..360, north 0, clockwise; and the antimeridian handled once — the ±180° line where longitudes wrap — so a route from 179 E to 179 W is 222 km rather than 40 000. Type GeoPt built by GeoAt, which stops the program on a bad coordinate, over GeoTryAt, which answers Result — compared with GeoNear, never =. Two points (GeoDistance GeoBearing GeoFinalBearing GeoDestination GeoMidpoint GeoAlong GeoAntipode GeoEquirect); where two paths cross (GeoIntersect GeoCrossTrack GeoAlongTrack GeoClosestOnLeg); routes as plain lists (GeoRouteLength GeoRouteLegs GeoRouteCumulative GeoRouteAt GeoRouteBearings GeoNearestOn GeoRouteBounds GeoSimplify GeoResample GeoWaypoints GeoCentroid GeoArea); boxes for cheap filtering (Type GeoBox, GeoBoxAround GeoInBox GeoBoxUnion GeoBoxCentre GeoBoundingCircle); coordinates as text, every reader answering Result with a 1-based position (GeoDms GeoFromDms GeoFormat GeoParse GeoCompass GeoFromCompass GeoHash GeoFromHash GeoHashBox GeoHashNeighbours GeoLocator GeoFromLocator); the sun, taking a date and never reading a clock (GeoJulian GeoSunPos GeoSunRise GeoSunSet GeoSunNoon GeoDayLength GeoTwilight GeoSolarDeclination GeoEquationOfTime); and navigation (GeoRhumbDistance GeoRhumbBearing GeoRhumbDestination GeoHorizon GeoGeographicRange GeoDeadReckon GeoZoneOffset GeoEcef GeoFromEcef). Ceilings, each stated where it bites: about 0.5 % from treating the Earth as a sphere, about a minute of time from the low-precision sun, and a polygon larger than half the Earth read as its complement. No networking machine is included, so none can be acquired by accident. Includes math, seq, str and julian, whose JulDayNumber is what GeoJulian now answers in one line.
• julian.shoddy — the calendar as arithmetic, and the one place the Gregorian leap rules are spelled: Type JulDate (JulYear JulMonth JulDay) built by JulOf, which stops the program on a bad date, over JulTryOf, which answers Result; the rules (JulIsLeap JulDaysInMonth); the two epochs, one constant apart (JulSerial JulFromSerial JulDayNumber — serial 0 is 1970-01-01, and a Julian day number is JulSerial + 2440587.5, spelled in exactly one line); and the arithmetic (JulDiff JulAddDays JulAddMonths JulWeekday, months clamped to month end, weekdays 1..7 with Monday 1). JulFromSerial refuses a fraction, because a number ending in .5 is usually a Julian day number on the wrong epoch. Proleptic — extended backwards before the calendar existed — pure, and it never reads a clock. ClockDate in clock.shoddy is the one bridge from “now”. Includes nothing.
• ephemeris.shoddy — the sky as arithmetic, and a closed Eph* surface: sidereal time (EphSidereal); Type EphSky (EphRa EphDec, degrees, deliberately not a GeoPt) and Type EphView (EphAlt EphAzim); the observer transform and separation (EphAltAz EphSeparation); the sun as a sky position (EphSun — rise and set at a place stay geo’s); the moon (EphMoon EphMoonDistance EphMoonPhase EphMoonAge EphMoonRise EphMoonSet EphMoonAltitude, the Almanac low-precision series, geocentric, about a third of a degree; rise and set answer Option, and a day without a moonrise answers None honestly); and the five naked-eye planets from the JPL approximate Keplerian elements, valid 1800..2050 (EphPlanet, chosen by EphMercury..EphSaturn — slot 3 is the Earth and is refused with the truth). Degrees at every boundary, metres for the one distance, dates as Julian day numbers, and no clock anywhere near it. Includes geo and math.
• random.shoddy — random numbers over the Rnd builtin, seedless by construction: Random RandomRange RandomInt Shuffle Sample (without replacement, capped at the length). Impure, like Rnd itself.
• neural.shoddy — feed-forward neural networks: one hidden Tanh layer, trained by mini-batch gradient descent with momentum. Type Net (W1 B1 W2 B2 — a gradient has the same shape, and so does a momentum velocity, so NetAdd/NetScale do all accumulation and updating), Type NetEval (Hidden Output), Type Head (Regress | Classify), Type Plan (Task Rate Moment Batch Epochs), Type Scaler (Center Spread), and Type Model (Weights Task Prep): NetNew NetNewScaled NetZero NetEvalAt NetOut NetPredict NetClassOf Softmax HeadOut Argmax NetOneHot NetGrad NetGradAt NetStep NetTrain ClassPlan RegressPlan NetFit NetMse NetAccuracy NetLogLoss NetClassAccuracy ScalerFit ScalerApply ScalerNone NetSave NetLoad NetSaveBin NetLoadBin ModelSave ModelLoad ModelPredict ModelClassOf NetWeightList NetFromList. Two heads, one backward pass: identity output under squared error and softmax output under cross-entropy have the same error signal at the output pre-activation (prediction - target). So NetGradAt has one line that knows the head, and NetGrad is a wrapper over it rather than a second copy. Three serialization formats over one canonical (input-major) weight order: text, one number per line, C#-interchangeable; binary over recio — a self-describing header (magic, ni, nh, no) then raw 8-byte doubles, so NetLoadBin(path) takes no architecture arguments and round trips are bit-exact; and ModelSave/ModelLoad, the same discipline over weights plus head and input scaler, so ModelPredict takes raw inputs and the training and serving transformations cannot drift apart. Impure at exactly two kinds of edge: the constructors’ initialization, and the training loops’ per-epoch shuffle — Seed once for reproducible runs. Classroom scale. Includes seq, matrix, random, file and recio.
• clock.shoddy — timing over the Ticks/Sleep/Clock builtins: monotonic measuring (Elapsed TimeIt SleepUntil) and wall-clock stamping (Stamp StampDate StampTime DateOf TimeOf, ISO-8601 shapes) plus FormatDuration, and ClockDate — one wall-clock reading lifted into julian.shoddy’s JulDate, the single bridge between this capability and the pure calendar. Includes str and julian.
• vt100.shoddy — VT100 terminal escape codes — the control sequences classic terminals understand. Every word returns the escape string; nothing prints itself. Cursor movement, SGR attributes, clearing, scroll regions, character sets, VT52 mode, the full DEC private-mode set/reset pairs — plus Type Vt100Key and EvalKey(raw) to classify keystrokes from InKey().
• terminal.shoddy — the raw console builtins, documented in one place: Print, Input, InputLine, InKey, and Args (which is core rather than terminal-owned, and is available in native hosts with no console involved — it is documented there because reading your own invocation is a console-shaped thing to want). It declares no words. All five are builtins the engine dispatches, so they are callable with no Include at all, and including this file gives you nothing. It exists so a reader looking for "how does a program read a keystroke" finds a machine named for the question, rather than needing to know §10 is here. The split against vt100 is raw versus protocol: reading a keystroke is not a VT100 idea, decoding the escape sequence that comes back is. So InKey is documented here, and EvalKey stays there. Neither includes the other.
• lineshaft.shoddy — the language’s own control-flow and execution-failure builtins: Call and Ifte, which route execution, and Error and Assert, which end it. It declares no words, for the same reason terminal does not. Named for the belt-and-pulley system that carried power from a mill’s engine out to each machine, which is what Call does with a quotation and the Engine. Deliberately narrow: the stack shuffles, comparisons and logic words stay core and are Appendix A’s, and this is not a testing machine — Assert is here because it is a way to stop, beside Error.
• keys.shoddy — physical-key classification for scribbler programs: Type GameKey (ArrowLeft…ArrowDown SpaceBar EnterKey EscKey TabKey BackKey CharKey(Code) OtherKey(Code)), ClassifyKey (a ScribblerKeyDown code → GameKey), KeyGlyph, IsKey.
• simplex.shoddy — linear programming: finding the best mix under constraints, stated as Problem(Costs, A, Rhs) (minimize Costs·x subject to Ax ≥ Rhs, x ≥ 0). Optimize → Solution(Status, X, Cost, DualPrices, Reduced, Iterations) — shadow prices and reduced costs included. Revised simplex over the matrix machine, solved via the dual, big-M artificials only when negative costs require them. Honest statuses: OPTIMAL UNBOUNDED INFEASIBLE MAXITER UNBOUNDED-OR-INFEASIBLE. SpProblem(Costs, SA, Rhs) states the same problem with a Sparse matrix, and SpOptimize solves it; Optimize converts and calls it, so there is one solver and one pivot sequence. Pricing skips a stored zero that a dense scan would have multiplied by nothing and added, which changes no bit of the answer or of Iterations. The basis inverse stays dense and whole, and it is variables-square, so the ceiling is hundreds of variables, while constraints are nearly free. Pure. Includes matrix and sparse.shoddy.
• mps.shoddy — reading MPS linear-programming files, the industry interchange format that feeds simplex: ParseMps LoadMps → Problem; ParseMpsSp LoadMpsSp → SpProblem; ParseMpsMip LoadMpsMip → MipProblem; the …Model forms of each → MpsModel MpsSpModel MpsMipModel (the problem plus variable and constraint names); …ZeroLower variants skip a BOUNDS section and pin every variable at zero. Assembly is sparse throughout: a COLUMNS section is already a triplet list, so SpFromEnts builds it, and the dense words answer through SpToMat. BOUNDS become rows (LO → x ≥ l, UP → −x ≥ −u, FX → both, BV → UP 1 and integer, PL → nothing), labelled NAME.LO/NAME.UP. Integer MARKERs are read and answered only by the Mip words; the plain words refuse such a file and name them. RANGES, MI, FR and a negative UP are refused — they break the x ≥ 0 frame. Includes mip, seq, simplex, sparse and str.shoddy.
• sparse.shoddy — matrices that are mostly zeros, stored by column: Type Sparse (Rows Cols ColIx ColVs — two parallel outer arrays, one entry per column, each an Array Of Number of ascending row indices and the matching values) and Type SpEnt (EntRow EntCol EntVal, the index-keyed triplet, deliberately distinct from mps’s name-keyed MpsEnt). SpFromEnts SpFromCols SpFromMat SpToMat SpGet SpNnz SpColIx SpColVs SpEnts SpColDot SpMatVec SpVecMat SpTransp SpAddCol SpAddRow SpShow. Duplicate triplets at one cell are summed left to right — the same order a dense assembly would use, so the two agree bit for bit — and a cell summing to zero is not stored. Column-major because its reader reads down: revised simplex prices a column at a time and never wants a row. Appending a column clones the outer spine of references while sharing every inner array, which is the one cheap way to grow a persistent structure. Shapes are refused at construction (mismatched lengths, out-of-range or non-ascending indices), never at read. matrix.shoddy stays the everyday dense grid; this pays only where the zeros dominate and the dimensions are large. Includes matrix and seq.shoddy.
• mip.shoddy — integer programming — optimization where some answers must come out whole — by LP-based branch and bound over simplex: Type MipProblem (Prob, an SpProblem, plus Ints, the 1-based indices that must come out whole), MipOptimize → Type MipSolution (Status X Cost Nodes Iterations), and MipFixed. Depth-first, most-fractional branching, floor child first, every node re-solved from scratch, pruned on the incumbent bound; node cap 100000. The search is one self-recursive word with the second child in tail position, so live depth is the tree’s depth and not its node count. Honest statuses: OPTIMAL INFEASIBLE UNBOUNDED-OR-INFEASIBLE MAXITER MAXNODES. No duals on a MipSolution — the last node’s LP duals are not the integer problem’s sensitivities. MipFixed pins the integers at the answer and hands back the LP whose duals are meaningful. Cold re-solves are affordable because the dual formulation makes the basis variables-square: a branch is one more single-entry column, so a node forty deep pivots on the same size of inverse as the root. Includes seq, simplex and sparse.shoddy.
• scribbler.shoddy — the friendly layer over the scribbler builtins: Type ScribblerEvent (ScribblerNone MouseDown/Move/Up KeyDown/Up Typed Tick Quit — all constructors Scribbler-prefixed against vt100’s KeyUp/KeyDown, every kind carrying an At timestamp), NextEvent (blocks at zero CPU) / PeekEvent / DecodeEvent, frame timing SetFps SinceLast, and shapes over the one pixel primitive: DrawHLine DrawVLine DrawLine (Bresenham) DrawRect FillRect DrawCircle FillCircle (midpoint) DrawPolyline DrawPolygon (Type Point) FloodFill (scanline, worklist — no recursion depth). Every drawing word returns the scribbler. Includes seq.shoddy and clock.shoddy.
• turtle.shoddy — purely functional turtle graphics drawing into a scribbler: Type Turtle threaded through NewTurtle Home Blit Close Title Forward Back TurnLeft TurnRight SetHeading SetXY MoveTo SetTowards DistanceTo PenUp PenDown SetPenColor. Heading is degrees, 0 = up, clockwise positive — the turtle convention — over the scribbler’s own pixel coordinates. Home is the window center, and position stays fractional so polygons close. Includes scribbler and math.shoddy.
• plotter.shoddy — statistical charts, stats doing the arithmetic and scribbler the drawing: NewPlot PlotTitle Histogram BarChart PieChart BoxPlot ScatterPlot, with the lower level exposed (Palette PlotColor DrawAxes XLabels YLabels ScaleTo BinCounts) for custom charts. Includes seq, scribbler and stats.shoddy.
• buzzer.shoddy — sound: note names, MIDI numbers, and a GW-BASIC-subset MML player — MML is a tiny text notation for tunes — over the sound builtins (Sound NoteOn NoteOff SoundQueue SoundStop SoundGain SoundWave, channels 1–8; audible under mill run/mill dap, a silent no-op headless — bad arguments raise even in silence). Type BuzzerNote (FreqHz/Ms; 0 = rest), WaveSquare WaveTriangle WaveSine (names for SoundWave’s argument), MidiFreq NoteMidi NoteFreq MmlNotes (pure: MML string → note list) and their guarded twins TryNoteMidi TryMmlNotes — the same answers as a Result rather than a stop; the stopping forms are defined over them, so there is one set of rules and not two — and Play PlayNotes. The frequency word is MidiFreq, never Freq — stats.shoddy owns Freq.
• net.shoddy — TCP/IP client and server over the gated socket builtins (the whole family needs --allow-net): client Connect Send SendLine Recv WaitRecv RecvAll Request HttpGet, server Listen ListenOn Accept WaitAccept Serve1, either end Ready Eof Peer Close. Handles are Numbers, shared with the 16-handle file table. Include it under a namespace — Include "net.shoddy" As Sock — only if the same program also includes turtle, the one machine that shares a word with it (Close). On its own it needs no As. Includes str, whose Join assembles a drained reply from its chunks instead of copying per chunk. Secure(sock, host) upgrades a connected socket to TLS in place, and ConnectTls/RequestTls/RecvAllTls are the secured mirrors of the plain words; on a secured handle Recv blocks and Ready is refused. WaitRecvFor(sock, ms) is the bounded poll for a peer that may never close. Server-side TLS is not supported.
• https.shoddy — an HTTP client over TLS, on net. The parsing half is pure and needs no --allow-net: HttpRequestText(method, path, host, headers) emits the exact request bytes, and HttpStatus, HttpReason, HttpHeaders, HttpHeader, HttpBody and HttpHead take a reply apart. Headers come back as a List Of Pair with names lowercased, so DictGetOr reads them unaided. The effectful half is HttpsGet(host, path, headers) and HttpsRequest. HTTP/1.0 with read-to-EOF, deliberately: no chunked decoder is needed, and none is present. Redirects are reported rather than chased, nothing is decompressed, and a body is bytes one per character, as ReadFile hands them over. Includes seq, net, dict and str.
• cuttle.shoddy — the runtime stack as a value: a heterogeneous Stack — one holding any mix of kinds — (numbers, strings, booleans, lists, quoted programs, pairs, money, matrices) and the pure algebra over it (CutPush CutPop CutDup CutDrop CutSwap CutOver CutNip CutTuck CutRot CutRoll CutPick CutDepth CutClear), plus kind tags, a shared display format (CutShow), structural equality (CutEqual) and cross-kind arithmetic (CutAdd CutSub CutMul CutLess). Every popping word answers a variant carrying the unchanged stack on underflow, rather than stopping the program. Includes seq, str, money and matrix.
• reckoner.shoddy — an interpreter for whitespace-tokenized RPN lines — reverse Polish notation, where 3 4 + means 3 plus 4 — over cuttle’s stack: the tokenizer, the evaluator, a registered-word dictionary (RckReg RckDef RckUnreg RckWords RckHelp), registers (STO/RCL), display modes, fifty-state history and UNDO, and the combinators IFT IFTE TIMES MAP FILTER FOLD. It knows no domain: every word beyond the engine core arrives through RckReg from a seed file. Nothing keyable stops the mill; a whole line evaluates or the state stands. Includes cuttle, seq, sinq, str and dict.

A further file per domain, the reckoner seeds, bridges the rest of the standard library into reckoner via its RckReg registration API. Each has no bearing outside that engine, so none is catalogued here individually. Reckoner’s own page lists every one of them with what each bridges, and does so from the tree rather than from a hand-written list that goes stale the moment a seed is added.

Appendix A. The concatenative core

The compilation target is itself a legal, complete language: Joy with BASIC vocabulary and layout. Every word is a pure Stack → Stack function, and composition is simply writing words next to each other. (This appendix is the law; the tutorial companion — worked traces, the stack drawn after every word — is The Stack.)

Def Fact            Rem ( n -- n! )
    Dup 0 =
    If Then
        Drop 1
    Else
        Dup 1 - Fact *

• Items on a line execute left to right; lines top to bottom.
• If (optionally If Then) ends its line, pops a Boolean, and runs one of the two indented branches — sugar for [ then ] [ else ] Ifte. Tokens before If on the same line execute first: Dup 0 < If Then.
• Take a, b, c pops into immutable named bindings, the topmost value going to the rightmost name. It is the escape hatch from Swap Rot Dup shuffle-hell — compare Factor’s :>.
• [ ... ] quotes code without running it. Combinators (Map, Fold, Call, Ifte, …) execute quotations.
• A quotation of literals doubles as a list (Joy-style homoiconicity — code and data share one shape); the typed surface’s { } lists compile to exactly this.
• Stack-effect comments Rem ( a b -- c ) or signatures Def f ( a b -- c ) document each word, and the weave-time linter checks call sites against the declared arity (see The linter).

Appendix B. Design notes

• Why no sigils? a%/a# were the type system of a language without declarations. As types make them a second, contradictable spelling of the same fact, and no sigil exists for List Of t or a generic return. ! (mutation, in the Scheme/Ruby reading) is banned by semantics — reserving it is the most purely functional decision available.
• Why layout-as-quotation? Indented branches compile to quotations. Newcomers read structured BASIC; the machine sees Joy. Nobody has to know.
• Why keep the core exposed? Point-free pipelines (data Filter(p) Map(f) Fold(z, g)) are often the clearest notation, and the desugaring rules stay honest when the target is a language you can actually write.
• Line numbers existed for editing and goto; both are gone.