oaknut-basic
Read the documentation — getting started, the command reference, and the API.
Work with the persistent artefacts a BBC BASIC program leaves behind — both the code and the data:
- Programs. Convert a program between its compact on-disc tokenised form
and a plain-text listing — the two directions a real BBC Micro performs when
you
LOADandLISTit — plus line numbering for source typed without numbers. - Data files. Read and write the channel-based files a program creates with
OPENOUTand writes withPRINT#andBPUT#, translating their tagged records to and from native Python values.
The problem
Both formats are bytecode, not text, and idiosyncratic to the BBC.
A tokenised program packs keywords like PRINT and GOTO into single bytes,
folds line numbers into each line's header, and scrambles a reference such as
GOTO 100 into a three-byte form that can never be mistaken for a line
terminator. A text codec decoding one produces garbage.
A PRINT# data file is just as surprising: PRINT#channel, 42 writes a type
tag and the number's bytes in reverse, not the characters 4 2; strings
go out length-prefixed and backwards, and reals use the BBC's packed 5-byte
floating-point format. The file is meant to be read back only by INPUT#.
oaknut-basic reproduces the BBC BASIC II ROM's behaviour exactly — every
token value and flag, the line-number encoding, the record tags and the 5-byte
REAL format — so a program round-trips between bytes and text byte-for-byte,
and a data file round-trips through Python values byte-for-byte.
Installation
Install as a tool for the oaknut-basic command, or add it to a project for
the library:
uv tool install oaknut-basic # the command-line tool
uv add oaknut-basic # the importable library
pip works identically with the same names. oaknut-basic requires Python
3.11 or newer.
Command-line usage
$ oaknut-basic --help
Usage: oaknut-basic [OPTIONS] COMMAND [ARGS]...
Tools for BBC BASIC programs and data files.
Options:
--version Show the version and exit.
--help Show this message and exit.
Commands:
data Read and write BBC BASIC data files...
detect Identify whether each FILE is a tokenised BBC BASIC program.
detokenise De-tokenise a stored BBC BASIC program into source text.
number Prepend ascending line numbers to an unnumbered BBC BASIC...
tokenise Tokenise BBC BASIC source text into a stored program.
The program commands read from a file or standard input and write to a file or
standard output, so each works file-to-file and as a pipe stage. That makes
them compose with oaknut-disc
to edit a program in place on a disc image:
disc get game.ssd MENU - | oaknut-basic detokenise > menu.bas
oaknut-basic tokenise menu.bas | disc put game.ssd MENU -
Tokenising and de-tokenising are exact inverses, so a program survives a
there-and-back trip unchanged. The tokenise command can also number
unnumbered source on the way in (--start / --step), exactly as typing it
under AUTO would.
The data subcommands turn a PRINT# data file into something host tools can
read. The inspect command shows its records as a table; decode and encode
are a lossless JSON round-trip pair for editing or generating a file:
oaknut-basic data inspect scores.dat
oaknut-basic data decode scores.dat | jq '.[0]'
echo '[42, "HELLO", 3.5]' | oaknut-basic data encode - scores.dat
Library usage
Programs are handled by the functions tokenise, detokenise, and
number_lines, all importable from oaknut.basic:
from oaknut.basic import detokenise, tokenise
program = tokenise('10 PRINT "HELLO"\n20 GOTO 10\n') # str -> bytes
listing = detokenise(program) # bytes -> str
assert tokenise(detokenise(program)) == program # byte-exact
print(program.hex(" "))
print(listing, end="")
Output:
0d 00 0a 0e 20 f1 20 22 48 45 4c 4c 4f 22 0d 00 14 0b 20 e5 20 8d 54 4a 40 0d ff
10 PRINT "HELLO"
20 GOTO 10
When the program lives in a disc image, prefer the path-object wrappers
DFSPath.read_basic / write_basic (and the ADFS equivalents), which compose
the codec with the disc's character encoding and the correct load address.
Data files are handled by a context-managed, file-like object. The
module-level open mirrors the built-in one: a mode string selects a reader,
a writer, or a combined object, and accepts a path or a binary stream. The
polymorphic write picks the record type from the Python value; typed
read_int / read_float / read_str read it back without coercion:
from oaknut.basic import datafile
with datafile.open("scores.dat", "w") as f:
f.write("ALICE") # str -> string record
f.write(42) # int -> integer record
f.write(3.5) # float -> real record
with datafile.open("scores.dat", "r") as f:
for value in f:
print(repr(value))
Output:
'ALICE'
42
3.5
Strings use the BBC acorn character set by default, and reals convert through
the packed 5-byte REAL format exposed as pack_float5 / unpack_float5.
References
- BBC BASIC — Wikipedia overview of the language and its versions.
- BBC BASIC program format — BeebWiki reference for the on-disc tokenised format and the token table.
- Format of a random access file —
BeebWiki background on the disc filing system that holds these files; the
PRINT#record tags and 5-byte REAL format are documented in this package's own API reference.
Part of oaknut
oaknut-basic is one package in the
oaknut monorepo of tools for Acorn
computer filesystems, files, and formats. It backs the read_basic /
write_basic methods of the oaknut-dfs and oaknut-adfs packages, and is
usable on its own for the .bas / .bbc programs and the data files BBC BASIC
leaves on a disc.
License
MIT — see LICENSE.
Metadata
Release files for oaknut-basic 13.6.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| oaknut_basic-13.6.0.tar.gz | 68.7 kB | Without provenance | Details for oaknut_basic-13.6.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| oaknut_basic-13.6.0-py3-none-any.whl | Python 3 | none | any | Details for oaknut_basic-13.6.0-py3-none-any.whl |
Total release size: 113.7 kB
Release files / oaknut_basic-13.6.0.tar.gz
| Download URL | oaknut_basic-13.6.0.tar.gz |
|---|---|
| Size | 68.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
15fcaad0b8a2ed540c3321f09c7899202688f8d2e23226c20c9b7613ead79e11
|
|
BLAKE2b-256 checksum How to use checksums |
9b5847b109a13272f4f54282137544a6588ef7957a3dbaca06641e539c91480d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / oaknut_basic-13.6.0-py3-none-any.whl
| Download URL | oaknut_basic-13.6.0-py3-none-any.whl |
|---|---|
| Size | 45.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c1b6357c0f3439fde11588f301213ca5bd7950985005f262b81164167128ea6f
|
|
BLAKE2b-256 checksum How to use checksums |
d18cf360f573704b8a7ab0a25971ce43fc63d5d671c51d69019465bb51cf71fa
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for oaknut-basic 13.6.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.