Cookbook

Composed recipes that chain oaknut-basic with the shell and with disc. Each is a pipeline you can paste and adapt.

Edit a program living on a disc image

Pull the tokenised program out of an image, de-tokenise it to a text file, edit it, then tokenise it back in place:

$ disc get game.ssd MENU - | oaknut-basic detokenise > menu.bas
$ $EDITOR menu.bas
$ oaknut-basic tokenise menu.bas | disc put game.ssd MENU -

disc get … - writes the raw bytes to standard output and disc put … - reads them from standard input, so no temporary copy of the tokenised form is ever needed.

Number, then tokenise, hand-typed source

Source typed without line numbers can be numbered and tokenised in one pipeline — or in a single tokenise invocation with auto-numbering:

$ oaknut-basic number draft.bas | oaknut-basic tokenise > PROG
$ oaknut-basic tokenise --start 10 --step 10 draft.bas > PROG   # equivalent

Convert a UTF-8 listing to a BBC program

A listing authored in a modern editor is UTF-8; the program on the image must be in the Acorn character set. tokenise bridges the two by default — UTF-8 in, Acorn-native tokenised bytes out, with £ and friends mapped across — so no flag is needed:

$ oaknut-basic tokenise menu.bas | disc put game.ssd MENU -

Pass --encoding acorn only when the source is already Acorn bytes, such as a listing taken straight off another image.

Batch-detokenise every program on a disc

List a disc’s files, pull each one out and de-tokenise it to a local .bas next to its Acorn name:

$ for name in $(disc ls game.ssd:$ --as tsv | cut -f1); do
>   disc get "game.ssd:$.$name" - | oaknut-basic detokenise > "$name.bas"
> done

Inspect a program without leaving the shell

De-tokenise straight to the pager to read a stored program as a listing:

$ disc get game.ssd MENU - | oaknut-basic detokenise | less