Cardigan: a CARDIAC cardboard computer simulator and IDE

Cardigan is an IDE for CARDIAC that runs in your browser. Write a program, run it, and step through it one instruction at a time while the machine's memory, accumulator and cards move in front of you. There is nothing to install, and it works offline once loaded.

Open Cardigan

What you can do

• Write programs in the six-column listing format, typing mnemonics and labels while Cardigan works out the numbers. Errors are underlined as you type.
• Run and debug with breakpoints, single steps, run to cursor, a watch list and variables you can edit.
• See every step on a picture of the machine: words fly between memory and the accumulator, cards feed in from the reader, and cells glow when they are run or written.
• Learn the machine: click anything for help on it, and the instruction clock shows what each opcode does.
• Open and save files: listings (.cq) and decks (.cqb) that other CARDIAC tools can use.
• Use a terminal: an xterm window for programs that print text, colour and all.

Getting started

1. Open Cardigan. The first time, a welcome box offers a short tour.
2. Pick an example from the Explorer, such as 02-countdown.
3. Press F5 to run it, or F11 to take one step at a time. The output appears in the Debug Console.
4. Change a line and run it again, or choose New in the Explorer to write your own.

If you've used vscode, you already know your way around: the Explorer and Run and Debug on the left, the editor in the middle, the Debug Console and Memory at the bottom, and the status bar along the bottom edge.

Documentation

• The machine in thirty seconds
• Writing a program
• Editor keys
• Files
• Loading and the PC
• Running and stepping
• Seeing what's happening
• Input and output
• Programs in several decks
• What isn't standard CARDIAC

The machine in thirty seconds

Cell 00 always holds 001. That is what lets a deck of cards load itself.

Writing a program

Programs are listings in the six-column layout from Brian Stuart's CARDIAC page:

ADDRESS  CONTENTS  LABEL  OPCODE  OPERAND  COMMENT
10       155       start  CLA     k6       x = 6
11       650              STO     x

The editor is plain text: type, select, cut, copy and paste as anywhere else. It also accepts the manual's own tables (address, contents, comments) as printed, so you can paste a program straight out of the book.

Writing with mnemonics. You don't have to work out the contents yourself:

1. Press Enter at the end of a line. The new line's address is filled in: the next cell.
2. Type a mnemonic such as STO, then Tab. It goes in the opcode column and the cursor moves to the operand.
3. Type the operand: a number (00 to 99), a label, or label+N. The contents fill in as you type: 651 for STO y when y is cell 51.

To label a line, type the label first, then Tab, then the mnemonic. DATA works like a mnemonic for cells that hold a number: DATA Tab 7 makes the cell 007.

Errors are underlined, red for an error and yellow for a warning; hover to read why. A line with an error isn't loaded into memory until it's fixed. Contents you type by hand are taken as written; if they disagree with the opcode and operand, the line gets a warning and Ctrl+. offers to fix it.

Editor keys

Files

• New starts an empty listing.
• Open, or drop files on the page: listings (.cq) and decks (.cqb). Each is known by what's in it, not by its name. Open a deck together with its listing (NAME.cq beside NAME.cqb) to debug it by its source.
• Save and Save As write a complete six-column listing, every contents column filled in.
• Export deck writes NAME.cqb: the bootstrap cards, an address card and a value card for each cell, and the pair that starts the program. Any CARDIAC simulator can load it.

Your work is kept in the browser between visits. A dot on a tab means unsaved changes.

Loading and the PC

A listing goes straight into memory, the manual's short cut of writing a program directly into the cells. The PC is put on the program's start: the cell a Start at NN. line names, or else the line labelled start, or else the first instruction.

A deck loads through the bootstrap, as it would in a real CARDIAC's reader. By default the loading happens instantly and the debugger stops on the program's first instruction; turn on Step through loading to watch the bootstrap read the cards.

To start somewhere else, drag the green arrow onto another cell or source line, click the PC in Variables and type an address, or right-click a cell or line and choose Set PC here.

Running and stepping

A run stops at a breakpoint, a halt, an INP waiting for input, or when you pause. Step Over is greyed out on purpose: CARDIAC has no call instruction, only JMP, so there is no telling a call from a jump. To get past a subroutine, put the cursor on the line after it and use Run to Cursor.

With Animate off the machine runs flat out and the display catches up when it stops. Turn it on and pick a speed to watch it run.

Seeing what's happening

• The current line is highlighted, with grey text at its end saying what the instruction is about to do with today's values.
• Memory shows the 100 cells as nixie tubes. A cell glows when it is run or written, and the glow fades step by step, so a loop's cells grade back from the PC.
• Arrows show what the next instruction will move, and where a jump will go. When you step, the value flies along the arrow.
• Variables shows the registers and every labelled cell. Watch takes a label, an address, label+N, or [x] for the cell whose address is in cell x. While stopped, click a value to change it.
• Self-modifying code is normal on CARDIAC. When a cell no longer holds what its line says, the line shows what's there now.

Input and output

• Output from OUT appears in the Debug Console.
• Input: put cards in ahead of time in Input cards, separated by spaces. When the cards run out, the program waits and the Debug Console asks for one; type a number from -999 to 999 and press Enter.
• Terminal (in the status bar) opens an xterm window that shows each value output as a number, or as a character for programs that print text: ASCII, the IBM PC's block characters, and ANSI colour codes. Keys typed there go in as input cards.

Programs in several decks

A program too big for memory can come as several decks, NAME.cqb, NAME.2.cqb and so on, opened together. A deck asks for the next by halting with the PC on its number: HRS 02 means "load deck 2". Cardigan puts that deck in the reader and starts the loader for you, in any order and as often as asked. The cells a deck doesn't load keep their values, and each deck's cells glow in their own colours.

What isn't standard CARDIAC

The machine follows the manual. Three conveniences go beyond it:

• HRS n loads deck n. On a paper CARDIAC, or another simulator, you load the next deck yourself.
• An INP with no card waits for you instead of stopping.
• Fast load runs the bootstrap without showing it. The result in memory is the same.

Outside the browser

Cardigan's assembler and machine are the same code as cardiaq, the open-source CARDIAC tools for the command line: carc assembles a listing into a deck, burn runs decks very fast, and ekg debugs and profiles them. A deck you export from Cardigan runs in burn, and a deck carc makes opens in Cardigan.

Feedback

Found a problem, or have an idea? Tell us on Discord, or write to bug@strangequery.com.

Open Cardigan