skoolkit 9.4__tar.gz → 9.5__tar.gz

{skoolkit-9.4/skoolkit.egg-info → skoolkit-9.5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: skoolkit
-Version: 9.4
+Version: 9.5
 Summary: A suite of tools for creating disassemblies of ZX Spectrum games
 Home-page: https://skoolkit.ca
 Author: Richard Dymond
@@ -11,11 +11,11 @@ Classifier: License :: OSI Approved :: GNU General Public License v3 or later (G
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Disassemblers
 Classifier: Topic :: Utilities
 Description-Content-Type: text/x-rst
@@ -43,7 +43,7 @@ With SkoolKit you can:
   Z80) or raw memory file
 * enable sna2ctl.py_ to generate a much better control file that more reliably
   distinguishes code from data by using a code execution map produced by an
-  emulator or rzxplay.py_
+  emulator, rzxplay.py_ or trace.py_
 * use sna2skool.py_ along with this control file to produce a disassembly of a
   snapshot or raw memory file
 * add annotations to this disassembly (or the control file) as you discover the

{skoolkit-9.4 → skoolkit-9.5}/c/csimulator.c

@@ -1679,10 +1679,9 @@ static void in_a(CSimulatorObject* self, void* lookup, int args[]) {
     unsigned value = 255;
     if (self->in_a_n_tracer) {
         byte* mem = self->memory;
-        unsigned port = PEEK(ADDR(REG(PC) + 1)) + 256 * REG(A);
-        PyObject* args = Py_BuildValue("(I)", port);
-        PyObject* rv = PyObject_CallObject(self->in_a_n_tracer, args);
-        Py_XDECREF(args);
+        PyObject* port = PyLong_FromLong(PEEK(ADDR(REG(PC) + 1)) + 256 * REG(A));
+        PyObject* rv = PyObject_CallOneArg(self->in_a_n_tracer, port);
+        Py_XDECREF(port);
         if (rv) {
             value = PyLong_AsLong(rv);
             Py_DECREF(rv);
@@ -1709,10 +1708,9 @@ static void in_c(CSimulatorObject* self, void* lookup, int args[]) {
 #endif
     unsigned value = 255;
     if (self->in_r_c_tracer) {
-        unsigned port = REG(C) + 256 * REG(B);
-        PyObject* args = Py_BuildValue("(I)", port);
-        PyObject* rv = PyObject_CallObject(self->in_a_n_tracer, args);
-        Py_XDECREF(args);
+        PyObject* port = PyLong_FromLong(REG(C) + 256 * REG(B));
+        PyObject* rv = PyObject_CallOneArg(self->in_a_n_tracer, port);
+        Py_XDECREF(port);
         if (rv) {
             value = PyLong_AsLong(rv);
             Py_DECREF(rv);
@@ -1774,10 +1772,9 @@ static void ini(CSimulatorObject* self, void* lookup, int args[]) {
     unsigned c = REG(C);
     byte value = 191;
     if (self->ini_tracer) {
-        unsigned port = c + 256 * b;
-        PyObject* args = Py_BuildValue("(I)", port);
-        PyObject* rv = PyObject_CallObject(self->in_a_n_tracer, args);
-        Py_XDECREF(args);
+        PyObject* port = PyLong_FromLong(c + 256 * b);
+        PyObject* rv = PyObject_CallOneArg(self->in_a_n_tracer, port);
+        Py_XDECREF(port);
         if (rv) {
             value = (byte)PyLong_AsLong(rv);
             Py_DECREF(rv);
@@ -5237,9 +5234,9 @@ static PyObject* CSimulator_exec_with_cb(CSimulatorObject* self, PyObject* args,
         }
 
         if (opcode == 0xD7) {
-            PyObject* args = Py_BuildValue("(b)", REG(A));
-            PyObject* rv = PyObject_CallObject(rst16_cb, args);
-            Py_XDECREF(args);
+            PyObject* arg = PyLong_FromLong(REG(A));
+            PyObject* rv = PyObject_CallOneArg(rst16_cb, arg);
+            Py_XDECREF(arg);
             if (rv == NULL) {
                 return NULL;
             }
@@ -5359,17 +5356,19 @@ static PyObject* CSimulator_accept_interrupt(CSimulatorObject* self, PyObject* a
 }
 
 static PyObject* CSimulator_trace(CSimulatorObject* self, PyObject* args, PyObject* kwds) {
-    static char* kwlist[] = {"", "", "", "", "", "", "", "", NULL};
+    static char* kwlist[] = {"", "", "", "", "", "", "", "", "", "", NULL};
     PyObject* start_obj;
     PyObject* stop_obj;
     unsigned long long max_operations;
     unsigned long long max_time;
     int interrupts;
     PyObject* draw;
+    PyObject* exec_map;
+    PyObject* keyboard;
     PyObject* disassemble;
     PyObject* trace;
 
-    if (!PyArg_ParseTupleAndKeywords(args, kwds, "OOKKiOOO", kwlist, &start_obj, &stop_obj, &max_operations, &max_time, &interrupts, &draw, &disassemble, &trace)) {
+    if (!PyArg_ParseTupleAndKeywords(args, kwds, "OOKKiOOOOO", kwlist, &start_obj, &stop_obj, &max_operations, &max_time, &interrupts, &draw, &exec_map, &keyboard, &disassemble, &trace)) {
         return NULL;
     }
 
@@ -5420,9 +5419,9 @@ static PyObject* CSimulator_trace(CSimulatorObject* self, PyObject* args, PyObje
         }
 
         if (disassemble != Py_None) {
-            PyObject* args = Py_BuildValue("(I)", pc);
-            i = PyObject_CallObject(disassemble, args);
-            Py_XDECREF(args);
+            PyObject* arg = PyLong_FromLong(pc);
+            i = PyObject_CallOneArg(disassemble, arg);
+            Py_XDECREF(arg);
             if (i == NULL) {
                 return NULL;
             }
@@ -5433,6 +5432,15 @@ static PyObject* CSimulator_trace(CSimulatorObject* self, PyObject* args, PyObje
             return NULL;
         }
 
+        if (exec_map != Py_None) {
+            PyObject* addr = PyLong_FromLong(pc);
+            int rv = PySet_Add(exec_map, addr);
+            Py_XDECREF(addr);
+            if (rv == -1) {
+                return NULL;
+            }
+        }
+
         if (trace == Py_None) {
             CHECK_SIGNALS;
         } else {
@@ -5464,14 +5472,16 @@ static PyObject* CSimulator_trace(CSimulatorObject* self, PyObject* args, PyObje
                         return NULL;
                     }
                 }
-                PyObject* args = Py_BuildValue("(OI)", scr, frame);
-                i = PyObject_CallObject(draw, args);
+                PyObject* args = Py_BuildValue("(OIO)", scr, frame, keyboard);
+                PyObject* rv = PyObject_CallObject(draw, args);
                 Py_XDECREF(args);
                 Py_XDECREF(scr);
-                if (i == NULL) {
+                if (rv == NULL) {
                     return NULL;
                 }
-                if (!PyObject_IsTrue(i)) {
+                int quit = !PyObject_IsTrue(rv);
+                Py_DECREF(rv);
+                if (quit) {
                     return Py_BuildValue("(IL)", 0, operations);
                 }
                 prev_frame = frame;
@@ -5549,9 +5559,9 @@ static PyObject* CSimulator_press_keys(CSimulatorObject* self, PyObject* args, P
         }
 
         if (disassemble != Py_None) {
-            PyObject* args = Py_BuildValue("(I)", pc);
-            i = PyObject_CallObject(disassemble, args);
-            Py_XDECREF(args);
+            PyObject* arg = PyLong_FromLong(pc);
+            i = PyObject_CallOneArg(disassemble, arg);
+            Py_XDECREF(arg);
             if (i == NULL) {
                 return NULL;
             }
@@ -5579,9 +5589,9 @@ static PyObject* CSimulator_press_keys(CSimulatorObject* self, PyObject* args, P
                     return NULL;
                 }
                 if (!PyObject_IsTrue(k)) {
-                    PyObject* args = Py_BuildValue("(I)", 0);
-                    PyObject* p = PyObject_CallObject(pop, args);
-                    Py_XDECREF(args);
+                    PyObject* arg = PyLong_FromLong(0);
+                    PyObject* p = PyObject_CallOneArg(pop, arg);
+                    Py_XDECREF(arg);
                     if (p == NULL) {
                         return NULL;
                     }
@@ -5641,9 +5651,9 @@ static int advance_tape(PyObject* tracer, unsigned long long* tracer_state, unsi
         if (index < block_max_index) {
             unsigned p = (unsigned)(edge / (edges[max_index] / 1000));
             if (p > *progress) {
-                PyObject* args = Py_BuildValue("(I)", p);
-                PyObject* rv = PyObject_CallObject(print_progress, args);
-                Py_XDECREF(args);
+                PyObject* arg = PyLong_FromLong(p);
+                PyObject* rv = PyObject_CallOneArg(print_progress, arg);
+                Py_XDECREF(arg);
                 if (rv == NULL) {
                     return -1;
                 }
@@ -6116,9 +6126,9 @@ static PyObject* CSimulator_load(CSimulatorObject* self, PyObject* args, PyObjec
         }
 
         if (disassemble != Py_None) {
-            PyObject* args = Py_BuildValue("(I)", pc);
-            i = PyObject_CallObject(disassemble, args);
-            Py_XDECREF(args);
+            PyObject* arg = PyLong_FromLong(pc);
+            i = PyObject_CallOneArg(disassemble, arg);
+            Py_XDECREF(arg);
             if (i == NULL) {
                 break;
             }
@@ -6157,9 +6167,7 @@ static PyObject* CSimulator_load(CSimulatorObject* self, PyObject* args, PyObjec
 
         int did_fast_load = 0;
         if (pc == 0x0556 && self->out7ffd & 0x10 && fast_load) {
-            PyObject* args = Py_BuildValue("(O)", self);
-            PyObject* fl = PyObject_CallObject(fast_load_method, args);
-            Py_XDECREF(args);
+            PyObject* fl = PyObject_CallOneArg(fast_load_method, (PyObject*)self);
             if (fl == NULL) {
                 break;
             }

{skoolkit-9.4 → skoolkit-9.5}/docs/_sources/changelog.rst.txt

@@ -1,6 +1,38 @@
 Changelog
 =========
 
+9.5 (2025-01-28)
+----------------
+* Dropped support for Python 3.8
+* Added the :ref:`comment generator <commentGenerator>` component
+* Added the ``--comments`` option to :ref:`sna2ctl.py` and :ref:`sna2skool.py`
+  (for generating instruction comments)
+* Added the ``Comments`` configuration parameter for
+  :ref:`sna2ctl.py <sna2ctl-conf>` and :ref:`sna2skool.py <sna2skool-conf>` (to
+  enable instruction comment generation)
+* :ref:`trace.py` now responds to keypresses while running with screen contents
+  displayed
+* Added the ``--map`` option to :ref:`trace.py` (for writing a code execution
+  map file)
+* Added the ``UserAgent`` configuration parameter for
+  :ref:`tap2sna.py <tap2sna-conf>` (to specify the User-Agent header in
+  HTTP/HTTPS requests)
+* Added support to the :ref:`CALL` macro for calling an arbitrary function
+* Added the ``--patch`` option to :ref:`snapmod.py` (for applying a binary
+  patch file)
+* The :ref:`REG` macro now always renders the IXh, IXl, IYh and IYl registers
+  with a lower case 'h' or 'l'
+* Added the :ref:`FRAMES` macro (as an alternative to the ``#UDGARRAY*`` macro,
+  which is now deprecated)
+* Made the :ref:`audio writer <audioWriter>` a pluggable component
+* Made the :ref:`code map reader <codeMapReader>` a pluggable component
+* Improved handling of TC2048, TC2068 and TS2068 Z80 snapshots
+* Fixed how :ref:`trace.py` builds a PNG image in 128K mode
+* Fixed the bug that prevents :ref:`skool2asm.py`, :ref:`skool2bin.py` and
+  :ref:`skool2html.py` from handling an instruction that crosses the 64K
+  boundary
+* Fixed how BIN expressions are evaluated in BASIC listings
+
 9.4 (2024-10-05)
 ----------------
 * Added support to :ref:`skool2bin.py <skool2bin-conf>` for reading

{skoolkit-9.4 → skoolkit-9.5}/docs/_sources/changelog8.rst.txt

@@ -261,8 +261,8 @@ SkoolKit 8.x changelog
 * Added support to the ``--ctl`` option of :ref:`sna2skool.py` and
   :ref:`snapinfo.py` for reading control files from a directory
 * Added the ``x`` and ``y`` parameters to the frame specification of the
-  :ref:`#UDGARRAY* <Animation>` macro (for specifying the coordinates at which
-  to render a frame of an animated image)
+  ``#UDGARRAY*`` macro (for specifying the coordinates at which to render a
+  frame of an animated image)
 * Added support for replacement fields in the ``args`` parameter of the
   :ref:`CALL` macro, in the integer parameters of the :ref:`CHR`, :ref:`D`,
   :ref:`INCLUDE`, :ref:`N`, :ref:`POKES`, :ref:`R` and :ref:`SPACE` macros, and

{skoolkit-9.4 → skoolkit-9.5}/docs/_sources/commands.rst.txt

@@ -924,6 +924,7 @@ skool file split into blocks of code and data.
   snapshot. FILE may be a regular file, or '-' for standard input.
 
   Options:
+    -C, --comments        Generate instruction comments.
     -e ADDR, --end ADDR   Stop at this address (default=65536).
     -h, --hex             Write upper case hexadecimal addresses.
     -I p=v, --ini p=v     Set the value of the configuration parameter 'p' to
@@ -945,7 +946,7 @@ to be a binary file.
 The ``-m`` option may be used to specify a code execution map to use when
 generating a control file. The supported file formats are:
 
-* Files created by the ``--map`` option of :ref:`rzxplay.py`
+* Files created by the ``--map`` option of :ref:`rzxplay.py` or :ref:`trace.py`
 * Profiles created by the Fuse emulator
 * Code execution logs created by the SpecEmu, Spud and Zero emulators
 * Map files created by the SpecEmu and Z80 emulators
@@ -962,6 +963,8 @@ Configuration
 current working directory or in `~/.skoolkit`, if present. The recognised
 configuration parameters are:
 
+* ``Comments`` - generate instruction comments (``1``), or don't (``0``, the
+  default)
 * ``Dictionary`` - the name of a file containing a list of allowed words, one
   per line; if specified, a string of characters will be marked as text only if
   it contains at least one of the words in this file
@@ -990,6 +993,9 @@ Configuration parameters may also be set on the command line by using the
 +---------+-------------------------------------------------------------------+
 | Version | Changes                                                           |
 +=========+===================================================================+
+| 9.5     | Added the ``--comments`` option and the ``Comments``              |
+|         | configuration parameter                                           |
++---------+-------------------------------------------------------------------+
 | 9.2     | Added support for reading code execution maps produced by         |
 |         | :ref:`rzxplay.py`                                                 |
 +---------+-------------------------------------------------------------------+
@@ -1089,6 +1095,7 @@ list::
                           which to read control files. PATH may be '-' for
                           standard input, or '0' to use no control file. This
                           option may be used multiple times.
+    -C, --comments        Generate instruction comments.
     -d SIZE, --defb SIZE  Disassemble as DEFB statements of this size.
     -e ADDR, --end ADDR   Stop disassembling at this address (default: 65536).
     -H, --hex             Write hexadecimal addresses and operands in the
@@ -1114,6 +1121,16 @@ By default, any files whose names start with the input filename (minus the
 '.bin', '.sna', '.szx' or '.z80' suffix, if any) and end with '.ctl' will be
 used as :ref:`control files <controlFiles>`.
 
+There are three options and configuration parameters that control whether
+`sna2skool.py` generates a comment for an instruction that has no comment
+defined in a control file. They are mutually exclusive and operate in the
+following order:
+
+* the ``--comments`` option or ``Comments`` configuration parameter (uses the
+  :ref:`comment generator <commentGenerator>` component)
+* the ``Text`` configuration parameter (shows byte values as ASCII text)
+* the ``Timings`` configuration parameter (shows instruction timings)
+
 .. _sna2skool-conf:
 
 Configuration
@@ -1126,6 +1143,8 @@ configuration parameters are:
   or decimal (``10``, the default)
 * ``Case`` - write the disassembly in lower case (``1``) or upper case (``2``,
   the default)
+* ``Comments`` - generate instruction comments (``1``), or don't (``0``, the
+  default)
 * ``CommentWidthMin`` - minimum width of the instruction comment field in the
   skool file (default: ``10``)
 * ``DefbSize`` - maximum number of bytes in a DEFB statement (default: ``8``)
@@ -1243,6 +1262,9 @@ Configuration parameters may also be set on the command line by using the
 +---------+-------------------------------------------------------------------+
 | Version | Changes                                                           |
 +=========+===================================================================+
+| 9.5     | Added the ``--comments`` option and the ``Comments``              |
+|         | configuration parameter                                           |
++---------+-------------------------------------------------------------------+
 | 9.3     | Added the ``Opcodes`` configuration parameter                     |
 +---------+-------------------------------------------------------------------+
 | 8.7     | Added the ``--defb`` option and the ``Timings`` configuration     |
@@ -1500,6 +1522,8 @@ To list the options supported by `snapmod.py`, run it with no arguments::
                           Copy a block of bytes of the given size from src in
                           RAM bank s to dest in RAM bank d. This option may be
                           used multiple times.
+    --patch [p:]a,file    Apply a binary patch file at address 'a' in RAM bank
+                          'p'. This option may be used multiple times.
     -p [p:]a[-b[-c]],[^+]v, --poke [p:]a[-b[-c]],[^+]v
                           POKE N,v in RAM bank p for N in {a, a+c, a+2c..., b}.
                           Prefix 'v' with '^' to perform an XOR operation, or
@@ -1517,6 +1541,8 @@ To list the options supported by `snapmod.py`, run it with no arguments::
 +---------+-------------------------------------------------------------------+
 | Version | Changes                                                           |
 +=========+===================================================================+
+| 9.5     | Added the ``--patch`` option                                      |
++---------+-------------------------------------------------------------------+
 | 9.1     | Added support for modifying SZX snapshots and 128K snapshots; the |
 |         | ``--move`` and ``--poke`` options can modify specific RAM banks   |
 +---------+-------------------------------------------------------------------+
@@ -1807,6 +1833,8 @@ configuration parameters are:
   separated by commas (default: ``$,02X,04X``); the byte and word formats are
   standard Python format specifiers for numeric values, and default to empty
   strings if not supplied
+* ``UserAgent`` - the value of the User-Agent header in HTTP/HTTPS requests
+  (default: empty string)
 
 ``TraceLine`` is a standard Python format string that recognises the following
 replacement fields:
@@ -1853,6 +1881,8 @@ Configuration parameters may also be set on the command line by using the
 +---------+-------------------------------------------------------------------+
 | Version | Changes                                                           |
 +=========+===================================================================+
+| 9.5     | Added the ``UserAgent`` configuration parameter                   |
++---------+-------------------------------------------------------------------+
 | 9.3     | Added support for PZX files; added support for the ``m`` (memory) |
 |         | replacement field in the ``TraceLine`` configuration parameter    |
 +---------+-------------------------------------------------------------------+
@@ -2005,6 +2035,7 @@ To list the options supported by `trace.py`, run it with no arguments::
     -D, --decimal         Show decimal values in verbose mode.
     -I p=v, --ini p=v     Set the value of the configuration parameter 'p' to
                           'v'. This option may be used multiple times.
+    --map FILE            Log addresses of executed instructions to a file.
     -m MAX, --max-operations MAX
                           Maximum number of instructions to execute.
     -M MAX, --max-tstates MAX
@@ -2027,7 +2058,8 @@ To list the options supported by `trace.py`, run it with no arguments::
     -s ADDR, --start ADDR
                           Start execution at this address.
     -S ADDR, --stop ADDR  Stop execution at this address.
-    --screen              Display screen contents while running.
+    --screen              Display screen contents and respond to keypresses
+                          while running.
     --state name=value    Set a hardware state attribute before execution
                           begins. Do '--state help' for more information. This
                           option may be used multiple times.
@@ -2053,6 +2085,9 @@ If the ``--screen`` option is given and `pygame`_ is installed, `trace.py` will
 use it to render the Spectrum's screen contents at 50 frames per second with a
 scale factor of 2 while running. The frame rate and scale factor can be changed
 by setting the ``ScreenFps`` and ``ScreenScale`` configuration parameters.
+While the screen is displayed, `trace.py` will also respond to keypresses, with
+the left shift key mapped to CAPS SHIFT on the Spectrum keyboard, and the left
+Ctrl key mapped to SYMBOL SHIFT.
 
 .. _trace-conf:
 
@@ -2120,6 +2155,9 @@ Configuration parameters may also be set on the command line by using the
 +---------+-------------------------------------------------------------------+
 | Version | Changes                                                           |
 +=========+===================================================================+
+| 9.5     | Responds to keypresses while the screen is displayed; added the   |
+|         | ``--map`` option                                                  |
++---------+-------------------------------------------------------------------+
 | 9.4     | Added the ``--screen`` option; added support for writing a PNG    |
 |         | file after execution has completed; added the ``PNGScale``,       |
 |         | ``ScreenFps`` and ``ScreenScale`` configuration parameters; added |

{skoolkit-9.4 → skoolkit-9.5}/docs/_sources/components.rst.txt

@@ -6,6 +6,9 @@ SkoolKit components
 SkoolKit relies on several components in order to function:
 
 * :ref:`assembler`
+* :ref:`audioWriter`
+* :ref:`codeMapReader`
+* :ref:`commentGenerator`
 * :ref:`ctlComposer`
 * :ref:`ctlGenerator`
 * :ref:`disassembler`
@@ -30,6 +33,9 @@ or in `~/.skoolkit`. The default contents of this section are as follows::
 
   [skoolkit]
   Assembler=skoolkit.z80.Assembler
+  AudioWriter=skoolkit.audio.AudioWriter
+  CodeMapReader=skoolkit.snactl
+  CommentGenerator=skoolkit.comment.CommentGenerator
   ControlDirectiveComposer=skoolkit.skoolctl.ControlDirectiveComposer
   ControlFileGenerator=skoolkit.snactl
   DefaultDisassemblyStartAddress=16384
@@ -66,6 +72,47 @@ must supply the following API functions, in common with skoolkit.z80.Assembler:
    :members: assemble, get_size
    :noindex:
 
+.. _audioWriter:
+
+Audio writer
+------------
+This class is responsible for writing audio files. It must supply the following
+API methods, in common with skoolkit.audio.AudioWriter:
+
+.. autoclass:: skoolkit.audio.AudioWriter
+   :members: formats, write_audio
+   :noindex:
+
+.. _codeMapReader:
+
+Code map reader
+---------------
+This object is reponsible for generating a list of code block start addresses
+and lengths from a code map file and corresponding snapshot. The code map
+reader object must supply the following API function, in common with
+skoolkit.snactl:
+
+.. automodule:: skoolkit.snactl
+   :members: read_map
+   :noindex:
+
+If **read_map()** encounters an error while reading a code map file, it should
+raise a CodeMapError:
+
+.. autoclass:: skoolkit.snactl.CodeMapError
+   :noindex:
+
+.. _commentGenerator:
+
+Comment generator
+-----------------
+This class is responsible for generating instruction comments. It must supply
+the following API method, in common with skoolkit.comment.CommentGenerator:
+
+.. autoclass:: skoolkit.comment.CommentGenerator
+   :members: get_comment
+   :noindex:
+
 .. _ctlComposer:
 
 Control directive composer

{skoolkit-9.4 → skoolkit-9.5}/docs/_sources/diy.rst.txt

@@ -125,8 +125,8 @@ text, data or code, and then edit the control file (`game.ctl`) accordingly.
 To generate a better control file, you could use a code execution map to tell
 `sna2ctl.py` where at least some of the code is in the snapshot. `sna2ctl.py`
 will read a map (otherwise known as a profile or trace) produced by
-:ref:`rzxplay.py`, Fuse, SpecEmu, Spud, Zero or Z80 when specified by the
-``-m`` option::
+:ref:`rzxplay.py`, :ref:`trace.py`, Fuse, SpecEmu, Spud, Zero or Z80 when
+specified by the ``-m`` option::
 
   $ sna2ctl.py -m game.map game.z80 > game.ctl
 

{skoolkit-9.4 → skoolkit-9.5}/docs/_sources/extending.rst.txt

@@ -122,7 +122,7 @@ With this method (and an appropriate implementation of the `build_sprite`
 method) in place, it's possible to use a ``#CALL`` macro like this::
 
   #UDGTABLE
-  { #CALL:sprite(3,jumping) }
+  { #CALL(sprite(3,jumping)) }
   { Sprite 3 (jumping) }
   TABLE#
 
@@ -141,11 +141,35 @@ this:
 
 With this method in place, it's possible to use a ``#CALL`` macro like this::
 
-  ; This ASM file was generated on #CALL:timestamp()
+  ; This ASM file was generated on #CALL(timestamp())
 
 Note that if the return value of a ``#CALL`` method contains skool macros, then
 they will be expanded.
 
+#CALL functions
+---------------
+The :ref:`CALL` macro can be used not only to call a method on an HtmlWriter or
+AsmWriter subclass, but also to call an arbitrary function. This approach might
+be preferable if you don't need to make use of any of the methods or attributes
+on the HtmlWriter/AsmWriter object, and the desired output is the same
+regardless of the output mode (HTML or ASM).
+
+Suppose you have the following string-reversing function defined in
+`mods/custom.py`:
+
+.. code-block:: python
+
+  def rev(s):
+      return s[::-1]
+
+Then you could call the **rev** function like this::
+
+  ; This string reversed is "#CALL(mods:custom.rev(#STR40000))".
+  t40000 DEFM "hello",0
+
+Note that unlike when calling a method on an HtmlWriter subclass, no `cwd`
+parameter is passed to the function.
+
 Skool macros
 ------------
 Another way to add a custom method is to implement it as a skool macro. The
@@ -253,6 +277,9 @@ to parse the parameters of a skool macro.
 .. autofunction:: skoolkit.skoolmacro.parse_image_macro
    :noindex:
 
+   .. versionchanged:: 9.5
+      Added the *xparse* and *xpargs* parameters.
+
    .. versionchanged:: 8.3
       Added the *fields* parameter.
 

{skoolkit-9.4 → skoolkit-9.5}/docs/_sources/man/sna2ctl.py.rst.txt

@@ -16,6 +16,9 @@ FILE is '-', ``sna2ctl.py`` reads standard input as a binary file.
 
 OPTIONS
 =======
+-C, --comments
+  Generate instruction comments.
+
 -e, --end `ADDR`
   Stop at this address. The default end address is 65536. `ADDR` must be a
   decimal number, or a hexadecimal number prefixed by '0x'.
@@ -33,8 +36,8 @@ OPTIONS
 
 -m, --map `FILE`
   Specify a code execution map to use. Code execution maps produced by
-  ``rzxplay.py`` and by the Fuse, SpecEmu, Spud, Zero and Z80 Spectrum
-  emulators are supported.
+  ``rzxplay.py`` and ``trace.py``, and by the Fuse, SpecEmu, Spud, Zero and Z80
+  Spectrum emulators are supported.
 
 -o, --org `ADDR`
   Specify the origin address of a binary file. The default origin address is
@@ -60,6 +63,8 @@ CONFIGURATION
 the current working directory or in ``~/.skoolkit``, if present. The recognised
 configuration parameters are:
 
+  :Comments: Generate instruction comments (``1``), or don't (``0``, the
+    default).
   :Dictionary: The name of a file containing a list of allowed words, one per
     line. If specified, a string of characters will be marked as text only if
     it contains at least one of the words in this file.

{skoolkit-9.4 → skoolkit-9.5}/docs/_sources/man/sna2skool.py.rst.txt

@@ -23,6 +23,9 @@ OPTIONS
   used, if present. If `PATH` is '-', standard input is used. If `PATH` is '0',
   no control file is used. This option may be used multiple times.
 
+-C, --comments
+  Generate instruction comments.
+
 -d, --defb `SIZE`
   Disassemble as DEFB statements of this size (instead of as code).
 
@@ -73,6 +76,8 @@ configuration parameters are:
     decimal (``10``, the default).
   :Case: Write the disassembly in lower case (``1``) or upper case (``2``, the
     default).
+  :Comments: Generate instruction comments (``1``), or don't (``0``, the
+    default).
   :CommentWidthMin: Minimum width of the instruction comment field in the skool
     file (default: ``10``).
   :DefbSize: Maximum number of bytes in a DEFB statement (default: ``8``).

{skoolkit-9.4 → skoolkit-9.5}/docs/_sources/man/snapmod.py.rst.txt

@@ -20,6 +20,11 @@ OPTIONS
   'dest' must each be a decimal number, or a hexadecimal number prefixed by
   '0x'.
 
+--patch `[p:]a,file`
+  Apply a binary patch file at address 'a' in RAM bank 'p'. This option may be
+  used multiple times. 'a' must be a decimal number, or a hexadecimal number
+  prefixed by '0x'.
+
 -p, --poke `[p:]a[-b[-c]],[^+]v`
   POKE N,v in RAM bank p for N in {a, a+c, a+2c..., b}. Prefix 'v' with '^' to
   perform an XOR operation, or '+' to perform an ADD operation. This option may

{skoolkit-9.4 → skoolkit-9.5}/docs/_sources/man/tap2sna.py.rst.txt

@@ -456,6 +456,8 @@ configuration parameters are:
     separated by commas (default: ``$,02X,04X``). The byte and word formats are
     standard Python format specifiers for numeric values, and default to empty
     strings if not supplied.
+  :UserAgent: The value of the User-Agent header in HTTP/HTTPS requests
+    (default: empty string).
 
 ``TraceLine`` is a standard Python format string that recognises the following
 replacement fields:

{skoolkit-9.4 → skoolkit-9.5}/docs/_sources/man/trace.py.rst.txt

@@ -39,6 +39,9 @@ OPTIONS
   overriding any value found in ``skoolkit.ini``. This option may be used
   multiple times.
 
+--map FILE
+  Log addresses of executed instructions to a file.
+
 -m, --max-operations `MAX`
   Maximum number of instructions to execute. Overrides the `STOP` address (if
   given).
@@ -86,7 +89,9 @@ OPTIONS
   hexadecimal number prefixed by '0x'.
 
 --screen
-  Display screen contents while running (requires pygame).
+  Display screen contents and respond to keypresses while running (requires
+  pygame). The left shift key is mapped to CAPS SHIFT on the Spectrum keyboard,
+  and the left Ctrl key is mapped to SYMBOL SHIFT.
 
 --state name=value
   Set a hardware state attribute before execution begins. Do ``--state help``