Shoddy Documentation

Welcome to Shoddy

Everything here, organised by what you came for

Useless Things Made Useful Through Skill

The mark’s three threads enter loose and run out woven: rag stock in, cloth out. The mark, the colours, and why they are these colours and no others, are in the heritage of the name.

Shoddy is a small programming language that looks like old-school BASIC. You build programs by combining values instead of changing them — a style called purely functional. For readers who already know languages: friendly typed syntax on the surface (parenthesized calls, infix operators, Let, records, Select Case pattern matching), compiled by the mill — Shoddy’s own compiler-and-runner — onto .NET, through a concatenative (Forth/Joy-style) stack core that remains a legal dialect you can write directly. Python’s layout, BASIC’s keywords, Joy’s soul.

Nothing changes in place. Let names a value once and never renames it. An “update” returns a new value, and repetition is a function calling itself — or Map/Filter/Fold doing it for you. The whole surface also translates down to stack code you can write yourself. The same Square is Def Square(n As Number) As Number / n * n, or Def Square ( Number -- Number ) / Dup *, and both are Shoddy. The standard library is written in that same language: one folder of Shoddy source per machine — a library, in Shoddy’s mill vocabulary — from seq and str out to neural nets and TCP/IP.

The showpieces

Mungo Caverns, a purely functional reimagining of our favourite text adventure — and Devil’s Dust, the language’s own name-story animated, with a tuning console that goes to eleven.

Two minutes to running

Runs anywhere .NET runs

A mill is not only a console program. Weaving is Shoddy’s word for compiling, and the woven result is an ordinary .NET program file. That same file runs at a terminal, inside an app, and from any .NET language — whole and unmodified, with one page of hosting behind all of it.

Start here — the tutorials

Build a real program from an empty folder, learn the method for driving the same craft with an AI assistant, then watch that method run at full size.

See it run — every mill

Complete programs woven from the machines. Each one splits into a pure core that only computes — tested automatically, no window needed — and a thin shell that only shows. Click through for the full write-up on each one, or start at the mills catalog.

Games

Demos

Data & statistics

Machine learning

Optimization

The machines — the whole shed

The standard library, one folder of Shoddy source per machine: graphics, sound, statistics, neural nets, an optimizer, keyed files, and TCP/IP networking — batteries included. Full word references live in the machines catalog.

Graphics & interaction

Core numerics

Sequences & text

Algebra

Money & finance

Statistics & machine learning

Markup & data formats

Data & storage

Networking

Optimization

Runtime stack

Pick your door

Want to build something first?

The tutorials start from an empty folder. Your First Mill walks a turtle spirograph all the way to a tested program, with build files and a debugger session. Building with an AI is the method and the templates for driving the whole thing from requirements instead of keystrokes.

Working with Copilot or Claude?

Grounding an Assistant — the standing instructions file to drop in your project, what to attach for a given task, and worked examples throughout: a small program, the prompt you would type, and the Shoddy that comes back. Every answer on the page was compiled and run.

New to Shoddy?

The Beginner’s Guide is the door in — eleven short chapters from Print("HELLO") to a grade book that keeps its roster on disk, with BASIC-veteran notes at the end. Install first: Setup is two steps, because the VS Code extension carries the whole toolchain with it. The Toolchain page is there when you want the mill on a command line.

Mid-program and need a word?

The Quick Reference — every builtin word, type, and syntax form on one page, plus a map of the library. Each machine’s full word reference lives in the machines catalog: statistics, matrices, neural networks, money, keyed files, optimization, graphics, turtles, charts, sound, TCP/IP networking, and more.

Want to see whole programs?

The Mills — complete, working programs woven from the machines: a cave crawl with a two-word parser, an overland-trail game, Pac in the terminal, an Invaders game, a neural income predictor, a neural species classifier, and a command-line optimizer. Each one splits into a pure core that only computes — tested automatically, no window needed — and a thin shell that only shows. Read them to see how Shoddy works at program scale.

Building a .NET app that should carry a mill?

Hosting — ShoddyWeave builds the mill from your csproj (the project file that tells .NET what to build), and ShoddyHost calls its words, or runs it whole through pipes. What the mill may do is granted permission by permission, everything not granted is refused, and each refusal says what to grant. The worked example is the Shoddy Reckoner: a calculator with a games shelf, each game the same woven program the console runs, unmodified.

Working on this — or any — tree with an AI assistant?

Fettler — the file, search and edit tools an assistant actually needs, as one program with an MCP front end and a command line. Find, search, read, write, edit, replace, move, copy, delete, and run a declared task — bounded to folders you declare, with no shell anywhere between it and the file. Its page carries the registration for VS Code, GitHub Copilot, Claude Code and Claude Desktop, and the settings that make it the only route to the tree rather than merely an available one. The AI page is the other half: what to tell an assistant so it writes Shoddy rather than something that merely looks like it.

Want the law, or the machinery underneath?

The Language Specification — including Appendix A, the stack core every surface form translates down to, and Appendix B, the design rationale. To watch that core run first — the stack drawn after every word, one worked function at a time — take The Stack.

Wondering about the name?

The Heritage of the Name — the shoddy mills of the West Riding of Yorkshire, which made new cloth from old rags for a century and a half, and why this language is built the same way. Five minutes, worth it.

Wondering who made it, and how?

Authorship — who designed and owns Shoddy, which tools were used and how, what is claimed and what deliberately is not, and the legal position behind all of it. The development record it cites is linked from that page.