oaknut-basic 12.13.1__tar.gz → 12.14.0__tar.gz

{oaknut_basic-12.13.1 → oaknut_basic-12.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oaknut-basic
-Version: 12.13.1
+Version: 12.14.0
 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

{oaknut_basic-12.13.1 → oaknut_basic-12.14.0}/src/oaknut/basic/__init__.py

@@ -81,7 +81,7 @@ from oaknut.basic.tokens import (
     TOKEN_TO_KEYWORD,
 )
 
-__version__ = "12.13.1"
+__version__ = "12.14.0"
 
 # Canonical load addresses for BBC BASIC programs on each host.
 # Programs saved by *SAVE on a real machine use these by default.

{oaknut_basic-12.13.1 → oaknut_basic-12.14.0}/src/oaknut/basic/cli.py

@@ -13,6 +13,7 @@ from __future__ import annotations
 
 import click
 from asyoulikeit.cli import report_output
+from oaknut.cli.help import use_plain_help
 
 from . import __version__
 
@@ -107,12 +108,14 @@ def number(input_stream, output_stream, encoding: str, start: int, step: int) ->
 
     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 ::
+    standard output, so the command works file-to-file:
 
+    \b
         oaknut-basic number menu.bas menu-numbered.bas
 
-    and as a pipe stage between ``disc get`` and ``disc put`` ::
+    and as a pipe stage between ``disc get`` and ``disc put``:
 
+    \b
         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
@@ -216,15 +219,17 @@ def tokenise(
 
     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`` ::
+    drops in alongside ``disc put``:
 
+    \b
         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 ::
+    that already carries line numbers:
 
+    \b
         oaknut-basic tokenise --start 10 unnumbered.bas MENU
 
     INPUT is read in --encoding (``utf-8`` by default, for source authored
@@ -274,8 +279,9 @@ def detokenise(input_stream, output_stream, encoding: str, dialect: str) -> None
 
     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`` ::
+    alongside ``disc get``:
 
+    \b
         oaknut-basic detokenise MENU menu.bas
         disc get game.ssd MENU - | oaknut-basic detokenise
 
@@ -317,8 +323,9 @@ def detect(ctx: click.Context, inputs, quiet: bool) -> None:
     line walk the BBC BASIC ROM performs to ``LIST`` a program — without
     de-tokenising, so unlabelled files harvested from disc images can be
     filtered. With no FILE, or ``-``, reads a single blob from standard
-    input ::
+    input:
 
+    \b
         oaknut-basic detect *
         disc get game.ssd MENU - | oaknut-basic detect
 
@@ -405,8 +412,9 @@ def decode(input_stream, encoding: str) -> None:
     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 ::
+    back to reals rather than integers:
 
+    \b
         oaknut-basic data decode scores.dat | jq '.[0]'
 
     The output is consumed by ``oaknut-basic data encode`` to rebuild the
@@ -447,8 +455,9 @@ def encode(input_stream, output_stream, encoding: str) -> None:
     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 ::
+    ``{"bytes": "hex"}`` raw (untagged) bytes:
 
+    \b
         echo '[42, "HELLO", 3.5]' | oaknut-basic data encode - scores.dat
 
     A hand-authored real must carry a decimal point (``3.0``, not ``3``),
@@ -505,8 +514,9 @@ 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 ::
+    with its byte offset, type and value:
 
+    \b
         oaknut-basic data inspect scores.dat
         oaknut-basic data inspect scores.dat --as json
 
@@ -527,5 +537,11 @@ def inspect(input_stream, encoding: str):
     return Reports(records=Report(data=table))
 
 
+# With the whole tree assembled, render every command's help with RST inline
+# markup stripped — the docstrings keep their markup for the Sphinx command
+# reference, but a terminal sees plain text, not stray backticks.
+use_plain_help(cli)
+
+
 if __name__ == "__main__":  # pragma: no cover
     cli()

{oaknut_basic-12.13.1 → oaknut_basic-12.14.0}/src/oaknut_basic.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: oaknut-basic
-Version: 12.13.1
+Version: 12.14.0
 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

{oaknut_basic-12.13.1 → oaknut_basic-12.14.0}/tests/test_cli.py

@@ -6,6 +6,7 @@ usage, the option parsing, and the byte/text (Acorn-encoding) boundary —
 rather than re-testing the numbering or tokenising logic itself.
 """
 
+import inspect
 from pathlib import Path
 
 import oaknut.basic as basic
@@ -141,6 +142,81 @@ class TestTopLevel:
         assert "number" in result.output
 
 
+def _walk_commands(command, path=()):
+    """Yield ``(argv, command)`` for every command and sub-command."""
+    yield list(path), command
+    for name, child in getattr(command, "commands", {}).items():
+        yield from _walk_commands(child, (*path, name))
+
+
+def _no_rewrap_lines(help_text):
+    """Return the stripped lines of a docstring's ``\\b`` no-rewrap blocks."""
+    if not help_text:
+        return []
+    lines = inspect.cleandoc(help_text).splitlines()
+    marked = []
+    in_block = False
+    for line in lines:
+        if line.strip() == "\b":
+            in_block = True
+        elif not line.strip():
+            in_block = False
+        elif in_block:
+            # The asyoulikeit reports epilog is a \b block of prose that
+            # the help formatter deliberately re-wraps.
+            if line.strip() == "Produces reports:":
+                in_block = False
+                continue
+            marked.append(line.strip())
+    return marked
+
+
+_ALL_COMMANDS = [
+    pytest.param(argv, id=" ".join(argv) or "oaknut-basic") for argv, _ in _walk_commands(cli)
+]
+
+
+class TestHelpFormatting:
+    """The example blocks in command docstrings must survive Click's rewrapper.
+
+    Click reflows every paragraph of a docstring unless it is preceded by
+    a ``\\b`` no-rewrap marker. Without one, a block of example command
+    lines is run together into a single paragraph and re-broken at
+    arbitrary points, which reads as two commands spliced together.
+    """
+
+    @pytest.mark.parametrize("argv", _ALL_COMMANDS)
+    def test_docstring_example_lines_survive_verbatim(self, argv):
+        command = cli
+        for name in argv:
+            command = command.commands[name]
+        expected = _no_rewrap_lines(command.help)
+        if not expected:
+            pytest.skip("no example block in this command's docstring")
+        runner = CliRunner()
+        result = runner.invoke(cli, [*argv, "--help"])
+        assert result.exit_code == 0
+        rendered = {line.strip() for line in result.output.splitlines()}
+        for line in expected:
+            assert line in rendered, (
+                f"example line reflowed away in `{' '.join(argv)} --help`: {line!r}"
+            )
+
+    @pytest.mark.parametrize("argv", _ALL_COMMANDS)
+    def test_no_rst_inline_markup_leaks(self, argv):
+        runner = CliRunner()
+        result = runner.invoke(cli, [*argv, "--help"])
+        assert result.exit_code == 0
+        assert "`" not in result.output
+
+    @pytest.mark.parametrize("argv", _ALL_COMMANDS)
+    def test_no_rst_literal_block_markers_leak(self, argv):
+        runner = CliRunner()
+        result = runner.invoke(cli, [*argv, "--help"])
+        assert result.exit_code == 0
+        assert " ::" not in result.output
+
+
 class TestTokeniseCommand:
     def test_pipe_tokenises_to_stdout(self):
         runner = CliRunner()
@@ -192,9 +268,7 @@ class TestTokeniseEncoding:
         # --encoding acorn treats the input as Acorn bytes already, so a
         # 0x60 byte is the £ literal verbatim.
         runner = CliRunner()
-        result = runner.invoke(
-            cli, ["tokenise", "--encoding", "acorn"], input=b'10 PRINT "\x60"\n'
-        )
+        result = runner.invoke(cli, ["tokenise", "--encoding", "acorn"], input=b'10 PRINT "\x60"\n')
         assert result.exit_code == 0
         assert b'"\x60"' in result.stdout_bytes