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. The mill is Shoddy’s own compiler and runner. It compiles a program onto .NET, the Microsoft platform the tools run on. For readers who already know other languages: the surface syntax is typed and friendly (parenthesized calls, infix operators, Let, records, Select Case pattern matching). Underneath, every program compiles onto a stack core: a small language where each word takes its inputs from the top of a pile of values and leaves its result there. That core is itself a legal dialect you can write directly (The Stack shows it running). The layout comes from Python, the keywords from BASIC, and the core from Joy, a stack language.

Nothing changes in place. Let names a value once and never renames it. An “update” returns a new value. Repetition is a function calling itself, or Map, Filter and 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. A machine is a library, in Shoddy’s mill vocabulary, and there is one file of Shoddy source per machine, from seq and str out to neural nets and TCP/IP.

The showpieces

Mungo Caverns, a purely functional port of the original 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

Optional downloads: tools for an AI assistant

Nothing in this section is needed to write or run Shoddy; the extension above is the whole install. These are separate downloads for an assistant working beside you: one gives it the calculator, and two bound what it may touch.

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. One page of hosting covers 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, with 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 file of Shoddy source per machine: graphics, sound, statistics, neural nets, an optimizer, keyed files and TCP/IP networking. 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 is 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 notes for BASIC veterans 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 has 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 are 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, with 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 tree, or any tree, with an AI assistant?

Fettler is the file, search and edit tools an assistant needs, as one program with an MCP front end and a command line. It can 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. Picker is the same boundary applied to SQL Server: SELECT and DESCRIBE inside databases you declare, and nothing else. 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, with 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. It takes five minutes.

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.