oaknut-basic 10.0.1__tar.gz

oaknut_basic-10.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Robert Smallshire
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

oaknut_basic-10.0.1/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: oaknut-basic
+Version: 10.0.1
+Summary: BBC BASIC tokeniser and detokeniser for Acorn 8-bit and 32-bit BASIC source files
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut
+Project-URL: Repository, https://github.com/rob-smallshire/oaknut
+Project-URL: Issues, https://github.com/rob-smallshire/oaknut/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# oaknut-basic
+
+BBC BASIC tokeniser and detokeniser for Acorn 8-bit BASIC (BBC
+Micro, Acorn Electron) and 32-bit BASIC V/VI (Archimedes, RISC OS)
+source files. Self-contained, no runtime dependencies on other
+`oaknut-*` packages.
+
+Part of the [oaknut](https://github.com/rob-smallshire/oaknut)
+monorepo.

oaknut_basic-10.0.1/README.md

@@ -0,0 +1,9 @@
+# oaknut-basic
+
+BBC BASIC tokeniser and detokeniser for Acorn 8-bit BASIC (BBC
+Micro, Acorn Electron) and 32-bit BASIC V/VI (Archimedes, RISC OS)
+source files. Self-contained, no runtime dependencies on other
+`oaknut-*` packages.
+
+Part of the [oaknut](https://github.com/rob-smallshire/oaknut)
+monorepo.

oaknut_basic-10.0.1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+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"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/rob-smallshire/oaknut"
+Repository = "https://github.com/rob-smallshire/oaknut"
+Issues = "https://github.com/rob-smallshire/oaknut/issues"
+
+[dependency-groups]
+test = [
+    "pytest>=8.0",
+]
+dev = [
+    "bump-my-version>=0.28.0",
+    "pre-commit>=3.0",
+    {include-group = "test"},
+]
+
+[tool.setuptools.dynamic]
+version = { attr = "oaknut.basic.__version__" }
+
+[tool.setuptools.packages.find]
+where = ["src"]

oaknut_basic-10.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

oaknut_basic-10.0.1/src/oaknut/basic/__init__.py

@@ -0,0 +1,60 @@
+"""BBC BASIC tokenisation and detokenisation.
+
+Tokenised BBC BASIC is a compact on-disc representation in which
+keywords like ``PRINT`` and ``GOTO`` are replaced with single bytes,
+line numbers are packed at the start of each line, and string
+literals and ``REM`` comments are stored in the Acorn character
+encoding. This module converts between source text and that byte
+representation.
+
+BBC BASIC is a language, not a text encoding — tokenised programs
+are bytecode, not text. The two functions here therefore work in
+``str`` ↔ ``bytes`` pairs and must never be composed with
+``DFSPath.read_text`` / ``write_text`` (which would silently mangle
+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.
+
+This module is deliberately self-contained and has no runtime
+dependencies on any other oaknut package.
+"""
+
+from __future__ import annotations
+
+__version__ = "10.0.1"
+
+# Canonical load addresses for BBC BASIC programs on each host.
+# Programs saved by *SAVE on a real machine use these by default.
+BBC_BASIC_LOAD_ADDRESS = 0x1900
+ELECTRON_BASIC_LOAD_ADDRESS = 0x0E00
+
+
+def tokenise(source: str) -> bytes:
+    """Tokenise BBC BASIC source text into its on-disc byte form.
+
+    Args:
+        source: BBC BASIC source as a Unicode string.
+
+    Returns:
+        Tokenised BASIC program bytes, ready to be written to a disc
+        image via ``DFSPath.write_bytes`` or ``ADFSPath.write_bytes``.
+
+    Raises:
+        NotImplementedError: The tokeniser has not yet been implemented.
+    """
+    raise NotImplementedError("BBC BASIC tokenisation is not yet implemented")
+
+
+def detokenise(data: bytes) -> str:
+    """Detokenise a BBC BASIC program into source text.
+
+    Args:
+        data: Tokenised BASIC program bytes, as read from a disc image.
+
+    Returns:
+        BBC BASIC source as a Unicode string.
+
+    Raises:
+        NotImplementedError: The detokeniser has not yet been implemented.
+    """
+    raise NotImplementedError("BBC BASIC detokenisation is not yet implemented")

oaknut_basic-10.0.1/src/oaknut_basic.egg-info/PKG-INFO

@@ -0,0 +1,29 @@
+Metadata-Version: 2.4
+Name: oaknut-basic
+Version: 10.0.1
+Summary: BBC BASIC tokeniser and detokeniser for Acorn 8-bit and 32-bit BASIC source files
+Author-email: Robert Smallshire <robert@smallshire.org.uk>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/rob-smallshire/oaknut
+Project-URL: Repository, https://github.com/rob-smallshire/oaknut
+Project-URL: Issues, https://github.com/rob-smallshire/oaknut/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# oaknut-basic
+
+BBC BASIC tokeniser and detokeniser for Acorn 8-bit BASIC (BBC
+Micro, Acorn Electron) and 32-bit BASIC V/VI (Archimedes, RISC OS)
+source files. Self-contained, no runtime dependencies on other
+`oaknut-*` packages.
+
+Part of the [oaknut](https://github.com/rob-smallshire/oaknut)
+monorepo.

oaknut_basic-10.0.1/src/oaknut_basic.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+LICENSE
+README.md
+pyproject.toml
+src/oaknut/basic/__init__.py
+src/oaknut_basic.egg-info/PKG-INFO
+src/oaknut_basic.egg-info/SOURCES.txt
+src/oaknut_basic.egg-info/dependency_links.txt
+src/oaknut_basic.egg-info/top_level.txt
+tests/test_basic.py

oaknut_basic-10.0.1/src/oaknut_basic.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

oaknut_basic-10.0.1/src/oaknut_basic.egg-info/top_level.txt

@@ -0,0 +1 @@
+oaknut

oaknut_basic-10.0.1/tests/test_basic.py

@@ -0,0 +1,62 @@
+"""Tests for the oaknut.dfs.basic module.
+
+The tokeniser and detokeniser are stubs that raise NotImplementedError
+until the real implementation lands. These tests lock in the module's
+public API shape so the stubs can be replaced with working code
+without disturbing callers.
+"""
+
+import oaknut.basic as basic
+import pytest
+
+
+class TestConstants:
+    def test_bbc_basic_load_address(self):
+        assert basic.BBC_BASIC_LOAD_ADDRESS == 0x1900
+
+    def test_electron_basic_load_address(self):
+        assert basic.ELECTRON_BASIC_LOAD_ADDRESS == 0x0E00
+
+
+class TestTokeniseStub:
+    def test_tokenise_raises_not_implemented(self):
+        with pytest.raises(NotImplementedError):
+            basic.tokenise('10 PRINT "Hello"')
+
+    def test_tokenise_raises_on_empty_input(self):
+        with pytest.raises(NotImplementedError):
+            basic.tokenise("")
+
+
+class TestDetokeniseStub:
+    def test_detokenise_raises_not_implemented(self):
+        with pytest.raises(NotImplementedError):
+            basic.detokenise(b"\x0d\xff")
+
+    def test_detokenise_raises_on_empty_input(self):
+        with pytest.raises(NotImplementedError):
+            basic.detokenise(b"")
+
+
+class TestModuleIsolation:
+    """The basic module is destined for a standalone oaknut-basic
+    package, so it must not import anything from the rest of
+    oaknut.dfs. Guard against regressions."""
+
+    def test_no_oaknut_dfs_imports_in_basic(self):
+        import ast
+        from pathlib import Path
+
+        source = Path(basic.__file__).read_text()
+        tree = ast.parse(source)
+
+        for node in ast.walk(tree):
+            if isinstance(node, ast.ImportFrom):
+                assert node.module is None or not node.module.startswith("oaknut.dfs"), (
+                    f"basic.py must not import from oaknut.dfs: {ast.dump(node)}"
+                )
+            elif isinstance(node, ast.Import):
+                for alias in node.names:
+                    assert not alias.name.startswith("oaknut.dfs"), (
+                        f"basic.py must not import from oaknut.dfs: {alias.name}"
+                    )