Janet on the Computer

The Janet ROM is Janet 1.41, a small Lisp, with this library on top. Anything that works in Janet works here. It has no network, threads or operating system calls, but files on the floppies work.

Tasks

A program is a set of tasks taking turns. While every task waits, the computer sleeps.

call does
(spawn f & args) runs (f ;args) as a task of its own
(sleep s) waits s seconds of the computer's time (other tasks run meanwhile)
(now), (ticks) the computer's clock, in seconds or game ticks (20 a second, only while it runs)
(run-file path) runs a file's forms in this task, in an environment of their own, as at start-up
(load path) runs a file's forms in this task's environment, so its definitions stay: at the REPL, they are the REPL's
(getline &opt prompt) waits for a line typed in this task's window: in the Shell, on the Shell's line; a program's window gets a line at its bottom meanwhile
(alarm & msg) prints ALARM: … in red

Each form typed at the REPL runs as a task too, so (sleep 10) doesn't stop the others. Ctrl+C stops it.

Processes

A process is a program with its own window, its own definitions, and its own tasks. startup.janet runs as one.

call does
(proc/start name f & args) starts (f ;args) as a new process, in a window of its own where what it prints goes; returns the window
(proc/list) the processes: [window name tasks] each
(proc/stop t) stops every task of the process in window t (as Ctrl+C in its window)
(proc/close t) ends it and closes its window (as its close box)
(proc/tab) the window of the process this task belongs to (nil at the Shell)
(proc/env t) its environment: ((proc/env t) 'x) is its x
(proc/new-window name &opt geometry) an empty window with a process of its own, for a program that draws its own screen (proc/new-tab is its old name)
(proc/start-window name geometry f & args) as proc/start, in a window of that geometry: [x y cw ch title flags]
(spawn-in env f & args) a task in another environment
(edit path), (files &opt dir), (inspect) the editor, file list and inspector windows

Drawing your own screen

A process can fill its window with text, boxes, buttons, lists, lines to type in, and areas that take the keyboard (see Wire). Positions and sizes are in character cells, inside the window. proc/start opens a window of 60 by 16; (ui/size t) is a window's size now, as the players left it. The screen is ui/screen-width by ui/screen-height cells (80 by 25 at start-up), and a window's inside can be ui/width by ui/height at most (78 by 22). (ui/mode 120 40) switches the screen to 120 by 40 (and these to 118 by 37), (ui/mode 80 25) back: ui/modes lists the two. A negative position counts from the right or bottom edge, and :fill as a size reaches the edge, so the layout follows a window the player sizes. t is the window, id a number you choose for each element (draw it again with the same id to change it), and colours are dye names such as :lime.

call does
(ui/text t id x y colour s &opt bg) a line of text
(ui/box t id x y w h colour) a filled rectangle
(ui/log t id x y w h), (ui/append t id colour s) a scrolling log, and text added to it
(ui/output env t id) what tasks in env print goes into log id
(ui/button t id x y w label f) a button: a click runs (f) as a task
(ui/list t id x y w h items f &opt chosen) rows of text: a click runs (f index); row chosen shows inverted
(ui/line t id x y w prompt f) a line the player types in: Enter runs (f text seq)
(ui/raw t id x y w h on-key &opt on-click) an area that takes the keyboard once clicked: (on-key key mods) for each key, (on-click x y)
(ui/remove t id), (ui/clear t) removes one element, or all of the window's
(ui/window t x y cw ch title &opt flags) opens window t (1 to 255); flags default to ui/standard, [:close :iconify :depth :size :drag]; also :borderless, :backdrop, :full (see Wire)
(ui/place t x y cw ch), (ui/size t) moves or sizes it on purpose; its content size now
(ui/focus t), (ui/front t), (ui/back t), (ui/unwindow t) gives it the keyboard, raises, lowers, closes it
(ui/menus t menus f), (ui/enable t menu item on) its menus on the screen bar: (f menu item) for a pick
(ui/ask t id title body buttons f) a requester: (f i) with the button's index
(ui/on-close t f), (ui/on-move t f) (f) for its close box (else it ends its process); (f cw ch) when a player moves or sizes it
(ui/title s) the screen's title on the menu bar
(ui/minimize t), (ui/restore t) minimises it to an icon on the desk, brings it back
(ui/pixmap pic p), (pix/load path) makes picture pic (1 to 4095, at most 256 on a screen) from {:w :h :palette :data}; reads one from a .pix file
(ui/image t id x y cw ch pic), (ui/icon t pic) a picture over cells; the picture of its icon when minimised
(ui/desk-icon t id x y label pic f), (ui/backdrop pic) an icon, as on the desk (a double-click runs (f)); the desk's picture (0: none)
(ui/tab t title), (ui/untab t) old names: a window as big as the screen allows, and ui/unwindow
(ui/send verb & args), (ui/busy t id seq on), (ui/dict t names) sends any Wire message; a line's busy mark; names Tab completes in window t (0: every window)
(app/launch dir), (app/list drive), (app/dir), (app/name dir) starts the application in dir ("A:/Calculator.app/", one of each); those on :a, :b or :ram; this program's own directory; "Calculator"

Elements are drawn in the order they were first made. A raw area's keys are the characters typed, or "enter", "backspace", "tab", "delete", "left", "right", "up", "down", "home", "end", "pageup", "pagedown", "insert" and "f1" to "f12", or a letter with Ctrl or Alt held. mods adds 1 for Shift, 2 for Ctrl and 4 for Alt. It is 0 for a typed character (Shift is in the character).

# a counter\ (var n 0)\ (defn show [t]\ (ui/text t 2 2 1\ :yellow (string\ "count: " n)))

(defn up [t]\ (++ n) (show t))\ (defn down [t]\ (-- n) (show t))

(defn counter []\ (def t (proc/tab))\ (ui/clear t)\ (ui/button t 3 2 3\ 5 "+1" |(up t))\ (ui/button t 4 8 3\ 5 "-1" |(down t))\ (show t))

(proc/start "counter"\ counter)

Type each form at the REPL, or save them in a file and Run it.

The bus

Addresses: 0 everyone, 17 to 255 a device. Colour channels are :white … :black, or 0 to 15 (bus/colours lists them; bus/types maps the packet types' numbers to their names).

call does
(bus/send target type index value) sends from this computer's address. type is :signal, :press, :power, :write, :read, :reply, :fault, :arrive, :data or a number
(bus/raw-send target source type index value) sends with any source address (it can pretend to be another device)
(bus/level ch) a colour channel's level, 0 to 1
(bus/set ch level) sets a colour channel. It holds until someone else writes it
(bus/wait &opt pred timeout) waits for a packet that pred accepts. nil after timeout seconds
(bus/on type f) runs (f packet) as a task for every packet of that type (or that a function accepts), until its program stops
(bus/on-press address f) runs (f index) whenever the button at that address is pressed
(bus/handlers-clear) forgets every bus/on
(bus/address) this computer's address, and whether it is on a bus

A packet is a struct: {:target :source :type :index :value}. At most 16 packets a tick go out from one computer.

Computers talk to each other with :data packets: the index is yours to choose, and the value is a string of up to 64 bytes. (bus/send 42 :data 1 "hello") sends one to the computer at 42, and (bus/send 0 :data 1 "hello") to every computer on the bus. Devices ignore them. The Applications floppy's BBS and Gorillas talk this way: open them with Files to see how.

Devices

call does
(light/set address level) a light's (or a button lamp's) brightness, 0 to 1
(device/write address reg value) sets a register
(device/read address reg) reads a register. An error if no reply comes within a second
(drive/move address height &opt timeout) sends a Linear Servo Drive's car to height and waits until it is there. An error on a fault, or after timeout seconds (default 60)
(drive/position address), (drive/state address) where its car is, and :idle, :in-position, :moving or :fault (:unknown for any other value; drive/states maps them)

Floppies

slurp, spit, file/open and import work on paths like a:/main.janet and b:/lib/util.janet: (import a:/lib/util) loads a:/lib/util.janet and names its definitions util/…. Janet keeps an imported file, so after you change it, (import a:/lib/util :fresh true) loads it again. The disks are FAT12, 1.44 MB.

ram:/ is a third drive, :ram: a 192 KB ramdisk, empty at start-up and gone at a reset or power off. It needs no formatting.

call does
(disk/format drive &opt label) formats the disk in :a, :b or :ram, erasing it (a label of 11 letters at most)
(disk/list &opt path) the names in a directory (a path, or :a, :b, :ram; default a:/); directories end in /
(disk/present? drive) is there a readable disk in it (:ram always is)
(disk/label drive), (disk/free drive) its label, and the bytes free
(disk/delete path), (disk/rename from to), (disk/mkdir path), (disk/exists? path) the rest

A small program

# a:/startup.janet:\ # the button at 30\ # toggles the lamp\ # at 31\ (var on false)

(defn toggle [_]\ (set on (not on))\ (light/set 31\ (if on 1 0)))\ (bus/on-press 30\ toggle)

# keep its task alive\ (forever (sleep 60))

Your own system

Every ROM starts at address 0x1000. With the Floppy Boot ROM in slot 1, the computer loads drive A's sector 0 (512 bytes) to address 0x100000 (slot 2's RAM) and jumps there, with a0 = 0 and a1 = 0x10000000. From there it's yours. The CPU is RV32IMAFDC in machine mode, with the timer, external and software (Break) interrupts.

address what
0x000000 to 0x000FFF unmapped (catches NULL)
slot n (1 to 8) from (n − 1) × 0x100000, its chip
0x10000000 info: +0 "EAC1", +0x10 + 4·k slot kind (0 none, 1 RAM, 2 ROM), +0x30 + 4·k size, +0x50 ticks (64-bit), +0x58 why it last reset
0x10001000 timer: a 64-bit compare at +0, interrupt while ticks ≥ compare
0x10002000 console: +0 send a byte, +4 read one (−1: none), +8 status (1 input, 2 room), +0xC interrupt enables
0x10003000 bus: packet registers; +0x14 send, +0x24 take the next received; channel levels from +0x80
0x10004000 floppies: drive, sector, RAM address, count, command (1 read, 2 write), status, interrupt, error
0x10005000 power: +0 write 1 to halt, 2 to reset; +4 Break pending
0x10007000 the screen's channel (Wire): registers as the console's

All device registers are 32-bit words.

The Computer · Wire · Back to the reference