Getting started

The oaknut-basic command-line tool converts BBC BASIC programs between text and their tokenised on-disc form, and numbers unnumbered source. It is built to sit in a Unix pipeline, so it composes naturally with disc get and disc put from the disc manual.

Install the tool with its [cli] extra (see Installation), then ask it what it can do:

$ oaknut-basic --help

Three subcommands

number

Prepend ascending line numbers to source that has none — the AUTO equivalent. See Auto-numbering.

tokenise

Turn a numbered listing into a stored, tokenised program.

detokenise

Turn a stored program back into a listing.

Every subcommand reads from a file or standard input and writes to a file or standard output, so the same invocation works file-to-file and in a pipe.

Files and pipes

Each command takes an optional INPUT and OUTPUT argument. Both default to - — standard input and standard output — so a bare command is a filter:

$ printf 'PRINT "HELLO"\nGOTO 10\n' | oaknut-basic number
10 PRINT "HELLO"
20 GOTO 10

Naming the files instead converts one to the other on disc:

$ oaknut-basic number draft.bas numbered.bas
$ cat numbered.bas
10 CLS
20 PRINT "HI"
30 END

Round-tripping

Tokenising and de-tokenising are exact inverses at the byte level, so a program survives a there-and-back trip unchanged:

$ printf '10 PRINT\n20 GOTO 10\n' | oaknut-basic tokenise | oaknut-basic detokenise
10 PRINT
20 GOTO 10

Composing with disc

Because every command is a stdio filter, it slots between disc get and disc put to edit a program in place on a disc image — pull the tokenised program out, de-tokenise it, and (after editing) tokenise it back:

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

Text encoding is handled at this boundary: by default the tool reads and writes the BBC Acorn character set, the form a program has on real media. Pass --encoding utf-8 when the host file is UTF-8. See Text encoding and line endings.