oaknut-basic 12.7.0__tar.gz → 12.7.2__tar.gz

{oaknut_basic-12.7.0 → oaknut_basic-12.7.2}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: oaknut-basic
-Version: 12.7.0
-Summary: BBC BASIC tokeniser and detokeniser for Acorn 8-bit and 32-bit BASIC source files
+Version: 12.7.2
+Summary: BBC BASIC tools: program tokeniser/de-tokeniser and PRINT#/INPUT# data-file reader/writer
 Author-email: Robert Smallshire <robert@smallshire.org.uk>
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-basic
@@ -16,6 +16,7 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: oaknut-exception>=10.0
+Requires-Dist: oaknut-codecs>=12.7
 Provides-Extra: cli
 Requires-Dist: oaknut-cli>=10.0; extra == "cli"
 Dynamic: license-file
@@ -34,22 +35,35 @@ Dynamic: license-file
 
 **[Read the documentation](https://rob-smallshire.github.io/oaknut/basic/)** — getting started, the command reference, and the API.
 
-Convert [BBC BASIC](https://en.wikipedia.org/wiki/BBC_BASIC) programs between
-their compact on-disc *tokenised* form and a plain-text listing — the two
-directions a real BBC Micro performs when you `LOAD` a program and `LIST` it —
-plus line numbering for source typed without numbers.
+Work with the persistent artefacts a [BBC BASIC](https://en.wikipedia.org/wiki/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 `LOAD` and `LIST` it — plus line numbering for source typed without
+  numbers.
+- **Data files.** Read and write the channel-based files a program creates with
+  `OPENOUT` and writes with `PRINT#` and `BPUT#`, translating their tagged
+  records to and from native Python values.
 
 ## The problem
 
-A tokenised BBC BASIC program is bytecode, not text: keywords like `PRINT` and
-`GOTO` are single bytes, line numbers are packed into each line's header, and a
-reference such as `GOTO 100` is scrambled into a three-byte form that can never
-be mistaken for a line terminator. A text codec cannot read it; decoding one as
-text produces garbage.
+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.
 
-`oaknut-basic` reproduces the **BBC BASIC II** ROM's tokeniser and de-tokeniser
-exactly — every token value, flag, and the line-number encoding — so a program
-round-trips between bytes and text **byte-for-byte**.
+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
 
@@ -70,21 +84,22 @@ uv add oaknut-basic                       # the importable library
 $ oaknut-basic --help
 Usage: oaknut-basic [OPTIONS] COMMAND [ARGS]...
 
-  Tools for BBC BASIC source and tokenised programs.
+  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.
   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.
 ```
 
-Every command reads from a file or standard input and writes to a file or
-standard output, so each works file-to-file and as a pipe stage. That makes it
-compose with [`oaknut-disc`](https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-disc)
+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`](https://github.com/rob-smallshire/oaknut/tree/master/packages/oaknut-disc)
 to edit a program in place on a disc image:
 
 ```
@@ -93,13 +108,24 @@ 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. `tokenise` can also number unnumbered source on
-the way in (`--start` / `--step`), exactly as typing it under `AUTO` would.
+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
 
-The library is function-shaped — `tokenise`, `detokenise`, and `number_lines`,
-all importable from `oaknut.basic`:
+Programs are handled by the functions `tokenise`, `detokenise`, and
+`number_lines`, all importable from `oaknut.basic`:
 
 ```python
 from oaknut.basic import tokenise, detokenise
@@ -113,12 +139,38 @@ 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:
+
+```python
+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:      # yields "ALICE", 42, 3.5
+        print(value)
+```
+
+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](https://en.wikipedia.org/wiki/BBC_BASIC) — Wikipedia overview of
   the language and its versions.
 - [BBC BASIC program format](https://beebwiki.mdfs.net/Program_format) —
   BeebWiki reference for the on-disc tokenised format and the token table.
+- [Format of a random access file](https://beebwiki.mdfs.net/Acorn_DFS_disc_format) —
+  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
 
@@ -126,7 +178,8 @@ the codec with the disc's character encoding and the correct load address.
 [oaknut](https://github.com/rob-smallshire/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 `.bas` / `.bbc` files outside a disc image.
+usable on its own for the `.bas` / `.bbc` programs and the data files BBC BASIC
+leaves on a disc.
 
 ## License
 

oaknut_basic-12.7.2/README.md

@@ -0,0 +1,163 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/rob-smallshire/oaknut/master/docs/basic/_static/oaknut-basic-logo.png" alt="oaknut-basic" width="300">
+</p>
+
+# oaknut-basic
+
+[![PyPI version](https://img.shields.io/pypi/v/oaknut-basic)](https://pypi.org/project/oaknut-basic/)
+[![CI](https://github.com/rob-smallshire/oaknut/actions/workflows/ci.yml/badge.svg)](https://github.com/rob-smallshire/oaknut/actions/workflows/ci.yml)
+[![Python versions](https://img.shields.io/pypi/pyversions/oaknut-basic)](https://pypi.org/project/oaknut-basic/)
+[![License: MIT](https://img.shields.io/pypi/l/oaknut-basic)](https://github.com/rob-smallshire/oaknut/blob/master/packages/oaknut-basic/LICENSE)
+[![Documentation](https://img.shields.io/badge/docs-online-blue)](https://rob-smallshire.github.io/oaknut/basic/)
+
+**[Read the documentation](https://rob-smallshire.github.io/oaknut/basic/)** — getting started, the command reference, and the API.
+
+Work with the persistent artefacts a [BBC BASIC](https://en.wikipedia.org/wiki/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 `LOAD` and `LIST` it — plus line numbering for source typed without
+  numbers.
+- **Data files.** Read and write the channel-based files a program creates with
+  `OPENOUT` and writes with `PRINT#` and `BPUT#`, 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 with the `[cli]` extra for the `oaknut-basic` command, or bare for the
+library only:
+
+```
+uv tool install "oaknut-basic[cli]"     # 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.
+  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`](https://github.com/rob-smallshire/oaknut/tree/master/packages/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`:
+
+```python
+from oaknut.basic import tokenise, detokenise
+
+program = tokenise('10 PRINT "HELLO"\n20 GOTO 10\n')   # str -> bytes
+listing = detokenise(program)                          # bytes -> str
+assert tokenise(detokenise(program)) == program        # byte-exact
+```
+
+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:
+
+```python
+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:      # yields "ALICE", 42, 3.5
+        print(value)
+```
+
+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](https://en.wikipedia.org/wiki/BBC_BASIC) — Wikipedia overview of
+  the language and its versions.
+- [BBC BASIC program format](https://beebwiki.mdfs.net/Program_format) —
+  BeebWiki reference for the on-disc tokenised format and the token table.
+- [Format of a random access file](https://beebwiki.mdfs.net/Acorn_DFS_disc_format) —
+  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](https://github.com/rob-smallshire/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](LICENSE).

{oaknut_basic-12.7.0 → oaknut_basic-12.7.2}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 name = "oaknut-basic"
 dynamic = ["version"]
 authors = [{ name = "Robert Smallshire", email = "robert@smallshire.org.uk" }]
-description = "BBC BASIC tokeniser and detokeniser for Acorn 8-bit and 32-bit BASIC source files"
+description = "BBC BASIC tools: program tokeniser/de-tokeniser and PRINT#/INPUT# data-file reader/writer"
 readme = "README.md"
 license = "MIT"
 license-files = ["LICENSE"]
@@ -23,7 +23,7 @@ classifiers = [
 # The tokeniser and de-tokeniser raise categorised errors from the shared
 # oaknut-exception hierarchy, so the CLI boundary can render them without a
 # traceback. That is the package's only runtime dependency.
-dependencies = ["oaknut-exception>=10.0"]
+dependencies = ["oaknut-exception>=10.0", "oaknut-codecs>=12.7"]
 
 # The `cli` extra pulls the shared CLI toolkit (Click, asyoulikeit, the
 # Acorn text codec and the categorised-error boundary) so this package

{oaknut_basic-12.7.0 → oaknut_basic-12.7.2}/src/oaknut/basic/__init__.py

@@ -15,27 +15,43 @@ the bytecode). The canonical way to move a BASIC program through a
 disc image is ``DFSPath.read_basic`` / ``write_basic``, which wrap
 these functions with the correct load-address default.
 
-Beyond ``oaknut-exception`` — the base layer, whose categorised errors
-the tokeniser and de-tokeniser raise — this module has no runtime
-dependencies on any other oaknut package.
+The tokeniser and de-tokeniser raise categorised errors from
+``oaknut-exception``; the data-file API additionally uses the ``acorn``
+text codec from ``oaknut-codecs`` for string records. Both are bottom-layer
+packages, so ``oaknut-basic`` stays independent of the file and disc-image
+layers.
 """
 
 from __future__ import annotations
 
+from oaknut.basic.datafile import (
+    BbcBasicDataFile,
+    BbcBasicDataFileBase,
+    BbcBasicDataReader,
+    BbcBasicDataWriter,
+)
 from oaknut.basic.detokeniser import detokenise
 from oaknut.basic.exceptions import (
     AlreadyNumberedError,
     BASICError,
+    DataFileError,
+    DataFileTypeMismatchError,
     DetokeniseError,
+    Float5RangeError,
+    IntegerRangeError,
     InvalidLineLengthError,
     LineNumberOrderError,
     LineNumberRangeError,
     LineTooLongError,
     MissingLineMarkerError,
+    StringTooLongError,
     TokeniseError,
     TruncatedProgramError,
+    TruncatedRecordError,
+    UnknownTagError,
     UnnumberedLineError,
 )
+from oaknut.basic.float5 import pack_float5, unpack_float5
 from oaknut.basic.numbering import (
     DEFAULT_LINE_NUMBER,
     DEFAULT_LINE_STEP,
@@ -43,7 +59,7 @@ from oaknut.basic.numbering import (
 )
 from oaknut.basic.tokeniser import tokenise
 
-__version__ = "12.7.0"
+__version__ = "12.7.2"
 
 # Canonical load addresses for BBC BASIC programs on each host.
 # Programs saved by *SAVE on a real machine use these by default.
@@ -57,16 +73,29 @@ __all__ = [
     "ELECTRON_BASIC_LOAD_ADDRESS",
     "AlreadyNumberedError",
     "BASICError",
+    "BbcBasicDataFile",
+    "BbcBasicDataFileBase",
+    "BbcBasicDataReader",
+    "BbcBasicDataWriter",
+    "DataFileError",
+    "DataFileTypeMismatchError",
     "DetokeniseError",
+    "Float5RangeError",
+    "IntegerRangeError",
     "InvalidLineLengthError",
     "LineNumberOrderError",
     "LineNumberRangeError",
     "LineTooLongError",
     "MissingLineMarkerError",
+    "StringTooLongError",
     "TokeniseError",
     "TruncatedProgramError",
+    "TruncatedRecordError",
+    "UnknownTagError",
     "UnnumberedLineError",
     "detokenise",
     "number_lines",
+    "pack_float5",
+    "unpack_float5",
     "tokenise",
 ]

{oaknut_basic-12.7.0 → oaknut_basic-12.7.2}/src/oaknut/basic/cli.py

@@ -12,6 +12,7 @@ installed with its ``[cli]`` extra; the library core never imports it.
 from __future__ import annotations
 
 import click
+from asyoulikeit.cli import report_output
 
 from . import __version__
 
@@ -44,7 +45,7 @@ class _BasicGroup(click.Group):
     help="Re-raise data and configuration errors with a full traceback.",
 )
 def cli(debug: bool) -> None:  # noqa: ARG001 - read by the group error boundary
-    """Tools for BBC BASIC source and tokenised programs."""
+    """Tools for BBC BASIC programs and data files."""
 
 
 def _validate_encoding(ctx: click.Context, param: click.Parameter, value: str) -> str:
@@ -275,5 +276,184 @@ def detokenise(input_stream, output_stream, encoding: str) -> None:
     output_stream.write(_listing_to_bytes(listing, encoding))
 
 
+@cli.group()
+def data() -> None:
+    """Read and write BBC BASIC data files (PRINT#/INPUT#/BPUT#/BGET#).
+
+    These commands work with the type-tagged record files BBC BASIC
+    creates with ``OPENOUT`` and writes with ``PRINT#``. ``inspect`` shows
+    a file's contents as a table; ``decode`` and ``encode`` are a lossless
+    JSON round-trip pair for editing and generating such files.
+    """
+
+
+def _kind_of(value: object) -> str:
+    """Return the record-type name for a value read from a data file."""
+    if isinstance(value, bool):  # pragma: no cover - reader never yields bool
+        raise TypeError("unexpected bool from a data file")
+    if isinstance(value, int):
+        return "int"
+    if isinstance(value, float):
+        return "real"
+    return "string"
+
+
+def _read_records(input_stream, encoding: str):
+    """Yield ``(offset, kind, value)`` for each tagged record in a stream."""
+    from oaknut.basic.datafile import open as open_datafile
+
+    with open_datafile(input_stream, "r", encoding=encoding) as reader:
+        while True:
+            offset = reader.tell()
+            value = reader.read()
+            if value is None:
+                return
+            yield offset, _kind_of(value), value
+
+
+@data.command()
+@click.argument(
+    "input_stream",
+    metavar="[INPUT]",
+    type=click.File("rb"),
+    default="-",
+    required=False,
+)
+@click.option(
+    "--encoding",
+    default="acorn",
+    show_default=True,
+    callback=_validate_encoding,
+    help="Text encoding of string records. Defaults to the BBC character set.",
+)
+def decode(input_stream, encoding: str) -> None:
+    """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.
+    """
+    import json
+
+    payload = [value for _offset, _kind, value in _read_records(input_stream, encoding)]
+    click.echo(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+@data.command()
+@click.argument(
+    "input_stream",
+    metavar="[INPUT]",
+    type=click.File("rb"),
+    default="-",
+    required=False,
+)
+@click.argument(
+    "output_stream",
+    metavar="[OUTPUT]",
+    type=click.File("wb"),
+    default="-",
+    required=False,
+)
+@click.option(
+    "--encoding",
+    default="acorn",
+    show_default=True,
+    callback=_validate_encoding,
+    help="Text encoding for string records. Defaults to the BBC character set.",
+)
+def encode(input_stream, output_stream, encoding: str) -> None:
+    """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.
+    """
+    import json
+
+    from oaknut.basic.datafile import open as open_datafile
+    from oaknut.exception import DataError
+
+    try:
+        payload = json.loads(input_stream.read())
+    except json.JSONDecodeError as error:
+        raise DataError(f"invalid JSON input: {error}") from error
+    if not isinstance(payload, list):
+        raise DataError("expected a JSON array of values")
+
+    with open_datafile(output_stream, "w", encoding=encoding) as writer:
+        for index, item in enumerate(payload):
+            if isinstance(item, bool):
+                raise DataError(f"item {index}: BBC BASIC has no boolean type")
+            if isinstance(item, int):
+                writer.write_int(item)
+            elif isinstance(item, float):
+                writer.write_float(item)
+            elif isinstance(item, str):
+                writer.write_str(item)
+            elif isinstance(item, dict) and set(item) == {"bytes"}:
+                try:
+                    writer.write_bytes(bytes.fromhex(item["bytes"]))
+                except (ValueError, TypeError) as error:
+                    raise DataError(f"item {index}: invalid hex in bytes value") from error
+            else:
+                raise DataError(f"item {index}: cannot encode JSON value {item!r}")
+
+
+@data.command()
+@click.argument(
+    "input_stream",
+    metavar="[INPUT]",
+    type=click.File("rb"),
+    default="-",
+    required=False,
+)
+@click.option(
+    "--encoding",
+    default="acorn",
+    show_default=True,
+    callback=_validate_encoding,
+    help="Text encoding of string records. Defaults to the BBC character set.",
+)
+@report_output(reports={"records": "The tagged records in the data file, in order."})
+def inspect(input_stream, encoding: str):
+    """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.
+    """
+    from asyoulikeit.tabular_data import Importance, Report, Reports, TableContent
+
+    table = TableContent(title="BBC BASIC data file")
+    table.add_column("index", "#", header=True)
+    table.add_column("type", "Type")
+    table.add_column("value", "Value")
+    table.add_column("offset", "Offset", importance=Importance.DETAIL)
+    for index, (offset, kind, value) in enumerate(_read_records(input_stream, encoding)):
+        table.add_row(index=index, type=kind, value=value, offset=offset)
+    return Reports(records=Report(data=table))
+
+
 if __name__ == "__main__":  # pragma: no cover
     cli()