Command reference¶
Every oaknut-basic subcommand. Each entry’s arguments and options
are live introspections of oaknut.basic.cli, so the page cannot
drift from what the installed binary accepts.
The numbering, tokenising and de-tokenising commands share the same
input/output model — an optional INPUT and OUTPUT defaulting to
standard input and standard output — described once in
Getting started. The --encoding option is covered in
Text encoding and line endings.
Numbering¶
oaknut-basic number¶
Prepend ascending line numbers to an unnumbered BBC BASIC program.
Reads BASIC source text from INPUT and writes the numbered program
to OUTPUT. Both default to -: INPUT to standard input, OUTPUT to
standard output, so the command works file-to-file
oaknut-basic number menu.bas menu-numbered.bas
and as a pipe stage between disc get and disc put
disc get game.ssd MENU - | oaknut-basic number --encoding acorn | disc put game.ssd MENU -
Text is read and written in --encoding (utf-8 by default; pass
acorn for the BBC character set). Input line endings are accepted
in any of the \n / \r / \r\n forms; output uses the
Acorn-native \r under the acorn encoding and \n
otherwise.
Line numbering mirrors the BBC’s AUTO start,step: internal
references such as GOTO are left untouched, so they must already
match the numbering requested here.
Usage
oaknut-basic number [OPTIONS] [[INPUT]] [[OUTPUT]]
Arguments
[INPUT](optional)[OUTPUT](optional)
Options
--encodingTEXTText encoding of INPUT and OUTPUT. Use “acorn” for the BBC character set (CR line endings) when writing to a disc image.
--startint [0..]Line number given to the first line.
--stepint [1..]Increment between successive line numbers.
Examples
$ printf 'CLS\nPRINT "HI"\nEND\n' | oaknut-basic number --step 5
10 CLS
15 PRINT "HI"
20 END
Tokenising¶
oaknut-basic tokenise¶
Tokenise BBC BASIC source text into a stored program.
Reads numbered BASIC source from INPUT and writes the tokenised
program bytes to OUTPUT. Both default to - (stdin / stdout), so it
drops in alongside disc put
oaknut-basic tokenise menu.bas MENU
cat menu.bas | oaknut-basic tokenise | disc put game.ssd MENU -
Passing –start and/or –step auto-numbers unnumbered source, exactly
as typing it under AUTO would; it is an error to use them on source
that already carries line numbers
oaknut-basic tokenise --start 10 unnumbered.bas MENU
INPUT is read in –encoding (utf-8 by default, for source authored
in a modern editor; pass acorn for the BBC character set, e.g.
source taken straight off a disc image).
Usage
oaknut-basic tokenise [OPTIONS] [[INPUT]] [[OUTPUT]]
Arguments
[INPUT](optional)[OUTPUT](optional)
Options
--encodingTEXTText encoding of the INPUT source. Use “acorn” for the BBC character set (e.g. source taken straight off a disc image).
--startint [0..]Auto-number from this line (as AUTO would); INPUT must be unnumbered. Defaults to 10 when only
--stepis given.--stepint [1..]Auto-numbering increment. Defaults to 10 when only
--startis given.
Examples
Numbered source in, tokenised program out:
$ printf '10 PRINT\n20 END\n' | oaknut-basic tokenise | od -An -tx1
0d 00 0a 06 20 f1 0d 00 14 06 20 e0 0d ff
With --start / --step, unnumbered source is numbered first, as
if typed under AUTO; numbered input is then an error
(see Auto-numbering):
$ printf 'PRINT\nEND\n' | oaknut-basic tokenise --start 10 | oaknut-basic detokenise
10 PRINT
20 END
De-tokenising¶
oaknut-basic detokenise¶
De-tokenise a stored BBC BASIC program into source text.
Reads a tokenised program from INPUT and writes numbered source text
to OUTPUT. Both default to - (stdin / stdout), so it drops in
alongside disc get
oaknut-basic detokenise MENU menu.bas
disc get game.ssd MENU - | oaknut-basic detokenise
OUTPUT is written in –encoding (utf-8 with host-native LF line
endings by default, for a host text file; pass acorn for the BBC
character set with CR endings, e.g. writing back to a disc image).
Pass --dialect v (or --dialect 5) for Archimedes / RISC OS
programs (BBC BASIC V), whose extended keywords use the &C6/&C7/&C8
two-byte escape tokens. The Roman (ii/v) and Arabic
(2/5) numerals are interchangeable.
Usage
oaknut-basic detokenise [OPTIONS] [[INPUT]] [[OUTPUT]]
Arguments
[INPUT](optional)[OUTPUT](optional)
Options
--encodingTEXTText encoding for the OUTPUT source. Use “acorn” for the BBC character set with CR line endings (e.g. writing back to a disc image).
--dialect[ii|2|v|5]BBC BASIC dialect, as a Roman or Arabic numeral. Use “v” (or “5”) for Archimedes / RISC OS programs, so the &C6/&C7/&C8 escape tokens (CASE, SYS, ORIGIN, …) decode correctly.
Examples
$ oaknut-basic detokenise PROG
10 PRINT "HELLO"
20 GOTO 10
Data files¶
The data subcommands read and write the type-tagged record files
BBC BASIC creates with OPENOUT and writes with PRINT#. encode
and decode are a lossless JSON round-trip pair; inspect shows a
file’s records as a table.
oaknut-basic data encode¶
Encode a JSON array of values into a BBC BASIC data file.
Reads the JSON array produced by oaknut-basic data decode from
INPUT and writes the tagged data file to OUTPUT. Each element becomes
one PRINT# record: a JSON integer becomes an integer, a JSON
number with a fractional part a real, a JSON string a string, and
{"bytes": "hex"} raw (untagged) bytes
echo '[42, "HELLO", 3.5]' | oaknut-basic data encode - scores.dat
A hand-authored real must carry a decimal point (3.0, not 3),
matching what decode emits.
Usage
oaknut-basic data encode [OPTIONS] [[INPUT]] [[OUTPUT]]
Arguments
[INPUT](optional)[OUTPUT](optional)
Options
--encodingTEXTText encoding for string records. Defaults to the BBC character set.
Examples
Each element of the JSON array becomes one record — a JSON integer an
integer, a number with a fractional part a real, a string a string,
and {"bytes": "hex"} raw bytes:
$ echo '[42, "HELLO", 3.5]' | oaknut-basic data encode - SCORES
oaknut-basic data inspect¶
Show the records in a BBC BASIC data file as a table.
Reads a PRINT#-tagged data file from INPUT and reports each record
with its byte offset, type and value
oaknut-basic data inspect scores.dat
oaknut-basic data inspect scores.dat --as json
Rendered through the shared report machinery, so --as display (the
default at a terminal), --as tsv (the default in a pipe) and
--as json all describe the same records; the JSON form carries the
faithful values for scripting.
Usage
oaknut-basic data inspect [OPTIONS] [[INPUT]]
Arguments
[INPUT](optional)
Options
--encodingTEXTText encoding of string records. Defaults to the BBC character set.
--as[display|json|tsv]Output format for tabular data. Defaults to ‘display’ for terminals, ‘tsv’ for pipes.
The standard report-output flags — --report, --no-reports, --all-reports, --header/--no-header, --detailed/--essential — are also accepted; see Output formats: --as.
Reports
recordsThe tagged records in the data file, in order.
Examples
$ oaknut-basic data inspect SCORES --as display
BBC BASIC data file
┏━━━┳━━━━━━━━┳━━━━━━━┳━━━━━━━━┓
┃ # ┃ Type ┃ Value ┃ Offset ┃
┡━━━╇━━━━━━━━╇━━━━━━━╇━━━━━━━━┩
│ 0 │ int │ 42 │ 0 │
│ 1 │ string │ HELLO │ 5 │
│ 2 │ real │ 3.5 │ 12 │
└───┴────────┴───────┴────────┘
oaknut-basic data decode¶
Decode a BBC BASIC data file to a JSON array of its values.
Reads a PRINT#-tagged data file from INPUT and writes a JSON array
to standard output, one element per record: integers and reals as JSON
numbers, strings as JSON strings, and raw bytes as {"bytes": "hex"}.
Reals keep their full float repr (e.g. 5.0) so they round-trip
back to reals rather than integers
oaknut-basic data decode scores.dat | jq '.[0]'
The output is consumed by oaknut-basic data encode to rebuild the
file byte-for-byte.
Usage
oaknut-basic data decode [OPTIONS] [[INPUT]]
Arguments
[INPUT](optional)
Options
--encodingTEXTText encoding of string records. Defaults to the BBC character set.
Examples
Reals keep their float repr (3.5) so they decode back to reals,
not integers:
$ oaknut-basic data decode SCORES
[
42,
"HELLO",
3.5
]