oaknut-cli 12.7.2__tar.gz → 12.8.1__tar.gz

{oaknut_cli-12.7.2/src/oaknut_cli.egg-info → oaknut_cli-12.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oaknut-cli
-Version: 12.7.2
+Version: 12.8.1
 Summary: Shared CLI toolkit for the oaknut family: the contributed-command axis and report-rendering helpers a disc command needs, below the filesystem packages.
 Author-email: Robert Smallshire <robert@smallshire.org.uk>
 License-Expression: MIT
@@ -23,7 +23,7 @@ Requires-Dist: oaknut-exception>=10.0
 Requires-Dist: oaknut-extension>=10.0
 Requires-Dist: oaknut-file>=10.0
 Requires-Dist: click>=8.1.7
-Requires-Dist: asyoulikeit>=1.2.0
+Requires-Dist: asyoulikeit>=1.3.0
 Dynamic: license-file
 
 # oaknut-cli

{oaknut_cli-12.7.2 → oaknut_cli-12.8.1}/pyproject.toml

@@ -27,7 +27,7 @@ dependencies = [
     "oaknut-extension>=10.0",
     "oaknut-file>=10.0",
     "click>=8.1.7",
-    "asyoulikeit>=1.2.0",
+    "asyoulikeit>=1.3.0",
 ]
 
 [project.urls]

{oaknut_cli-12.7.2 → oaknut_cli-12.8.1}/src/oaknut/cli/__init__.py

@@ -32,11 +32,13 @@ from oaknut.cli.reports import (
     SECTOR_SIZE,
     address_cell,
     bytes_cell,
+    control_pictures,
     kv_table,
     size_cell,
+    text_cell,
 )
 
-__version__ = "12.7.2"
+__version__ = "12.8.1"
 
 __all__ = [
     "COMMAND_KIND",
@@ -48,6 +50,8 @@ __all__ = [
     "SECTOR_SIZE",
     "address_cell",
     "bytes_cell",
+    "control_pictures",
     "kv_table",
     "size_cell",
+    "text_cell",
 ]

{oaknut_cli-12.7.2 → oaknut_cli-12.8.1}/src/oaknut/cli/reports.py

@@ -15,6 +15,40 @@ from oaknut.file.capacity import format_capacity
 #: Acorn discs are addressed in 256-byte sectors throughout.
 SECTOR_SIZE = 256
 
+# The Unicode Control Pictures block (U+2400–U+241F) holds a visible,
+# inert glyph for each C0 control character (0x00–0x1F); U+2421 (␡) is
+# the symbol for DEL (0x7F). Mapping to these never emits an active
+# control code, so a terminal is never driven by data read off a disc.
+_CONTROL_PICTURES = {codepoint: chr(0x2400 + codepoint) for codepoint in range(0x20)}
+_CONTROL_PICTURES[0x7F] = "␡"
+_CONTROL_PICTURES_TABLE = str.maketrans(_CONTROL_PICTURES)
+
+
+def control_pictures(text: str) -> str:
+    """Render C0 control characters and DEL as Unicode Control Pictures.
+
+    Acorn names and titles are stored as arbitrary bytes and may carry
+    control characters (a disc title decorated with a form-feed, say).
+    This replaces each with the matching glyph from the Control Pictures
+    block so it is visible and inert; all other characters pass through.
+    """
+    return text.translate(_CONTROL_PICTURES_TABLE)
+
+
+def text_cell(text: str) -> str | ByAudience:
+    """On-disc text that may contain control characters, as a cell.
+
+    Clean text is returned unchanged, so the common case is untouched.
+    When control characters are present the cell becomes audience-aware:
+    machine formatters (JSON, TSV) keep the raw string for a faithful
+    round-trip, while the display formatter shows :func:`control_pictures`
+    so the terminal is never driven by active control codes.
+    """
+    pretty = control_pictures(text)
+    if pretty == text:
+        return text
+    return ByAudience(machine=text, human=pretty)
+
 
 def size_cell(sectors: int) -> ByAudience:
     """A capacity (given in sectors) as an audience-aware cell.

{oaknut_cli-12.7.2 → oaknut_cli-12.8.1/src/oaknut_cli.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oaknut-cli
-Version: 12.7.2
+Version: 12.8.1
 Summary: Shared CLI toolkit for the oaknut family: the contributed-command axis and report-rendering helpers a disc command needs, below the filesystem packages.
 Author-email: Robert Smallshire <robert@smallshire.org.uk>
 License-Expression: MIT
@@ -23,7 +23,7 @@ Requires-Dist: oaknut-exception>=10.0
 Requires-Dist: oaknut-extension>=10.0
 Requires-Dist: oaknut-file>=10.0
 Requires-Dist: click>=8.1.7
-Requires-Dist: asyoulikeit>=1.2.0
+Requires-Dist: asyoulikeit>=1.3.0
 Dynamic: license-file
 
 # oaknut-cli

{oaknut_cli-12.7.2 → oaknut_cli-12.8.1}/src/oaknut_cli.egg-info/SOURCES.txt

@@ -11,4 +11,5 @@ src/oaknut_cli.egg-info/dependency_links.txt
 src/oaknut_cli.egg-info/requires.txt
 src/oaknut_cli.egg-info/top_level.txt
 tests/test_commands.py
-tests/test_help.py
+tests/test_help.py
+tests/test_reports.py

{oaknut_cli-12.7.2 → oaknut_cli-12.8.1}/src/oaknut_cli.egg-info/requires.txt

@@ -2,4 +2,4 @@ oaknut-exception>=10.0
 oaknut-extension>=10.0
 oaknut-file>=10.0
 click>=8.1.7
-asyoulikeit>=1.2.0
+asyoulikeit>=1.3.0

oaknut_cli-12.8.1/tests/test_reports.py

@@ -0,0 +1,38 @@
+"""Tests for the shared report-rendering cell helpers."""
+
+from __future__ import annotations
+
+from asyoulikeit import ByAudience
+from oaknut.cli import control_pictures, text_cell
+
+
+class TestControlPictures:
+    def test_c0_controls_map_to_pictures_block(self):
+        # Every C0 control (0x00–0x1F) maps to U+2400 + codepoint.
+        for c in range(0x20):
+            assert control_pictures(chr(c)) == chr(0x2400 + c)
+
+    def test_del_maps_to_its_symbol(self):
+        assert control_pictures("\x7f") == "␡"  # ␡
+
+    def test_printable_text_unchanged(self):
+        assert control_pictures("Pascal 1.2 (c)") == "Pascal 1.2 (c)"
+
+    def test_mixed_title(self):
+        # The Oxford Pascal disc title: form-feed, then "Pascal", LF, CR.
+        assert control_pictures("\x0cPascal\n\r") == "␌Pascal␊␍"
+
+
+class TestTextCell:
+    def test_clean_text_is_plain_string(self):
+        # No control characters → no need to wrap; output is identical to
+        # passing the bare string, keeping the common case untouched.
+        assert text_cell("HELLO") == "HELLO"
+        assert not isinstance(text_cell("HELLO"), ByAudience)
+
+    def test_control_text_is_audience_aware(self):
+        cell = text_cell("\x0cPascal\n\r")
+        assert isinstance(cell, ByAudience)
+        # Machines keep the raw bytes; humans get control pictures.
+        assert cell.machine == "\x0cPascal\n\r"
+        assert cell.human == "␌Pascal␊␍"