Documentation and Changelog for debug printing and Signal

docs/Plugins.rst

@@ -392,6 +392,102 @@ Otherwise somewhat similar to `gui/quickcmd`.
 .. image:: images/command-prompt.png
 
 
+.. _debug:
+
+debug
+=====
+Manager DFHack runtime debug prints. Debug prints are grouped by plugin name,
+category name and print level. Levels are ``trace``, ``debug``, ``info``,
+``warning`` and ``error``.
+
+The runtime message printing is controlled using filters. Filters set minimum
+visible message to all matching categories. Matching uses regular expression
+that allows listing multiple alternative matches or partial name matches.
+Persistent filters are stored in ``dfhack-config/runtime-debug.json``.
+
+Oldest filters are applied first. That means a newer filter can override the
+older printing level selection.
+
+Usage: ``debugfilter [subcommand] [parameters...]``
+
+Following subcommands are supported.
+
+Regular expression syntax
+-------------------------
+
+Syntax is C++ version of ECMA-262 grammar (Javascript regular expression).
+Deails of differences can be found from
+https://en.cppreference.com/w/cpp/regex/ecmascript
+
+help
+----
+Give overall help or a detailed help for a subcommand.
+
+Usage: ``debugfilter help [subcommand]``
+
+category
+--------
+List available debug plugin and category names.
+
+Usage: ``debugfilter category [plugin regex] [category regex]``
+
+The list can be filtered using optional regex parameters. If filters aren't
+given then the it uses ``"."`` regex which matches any character. The regex
+parameters are good way to test regex before passing them to ``set``.
+
+filter
+------
+List active and passive debug print level changes.
+
+Usage: ``debugfilter filter [id]``
+
+Optional ``id`` parameter is the id listed as first column in the filter list.
+If id is given then the command shows information for the given filter only in
+multi line format that is better format if filter has long regex.
+
+set
+---
+Creates a new debug filter to set category printing levels.
+
+Usage: ``debugfilter set [level] [plugin regex] [category regex]``
+
+Adds a filter that will be deleted when DF process exists or plugin is unloaded.
+
+Usage: ``debugfilter set persistent [level] [plugin regex] [category regex]``
+
+Stores the filter in the configuration file to until ``unset`` is used to remove
+it.
+
+Level is the minimum debug printing level to show in log.
+
+* ``trace``: Possibly very noisy messages which can be printed many times per second
+
+* ``debug``: Messages that happen often but they should happen only a couple of times per second
+
+* ``info``: Important state changes that happen rarely during normal execution
+
+* ``warining``: Enabled by default. Shows warnings about unexpected events which code managed to handle correctly.
+
+* ``error``: Enabled by default. Shows errors which code can't handle without user intervention.
+
+unset
+-----
+Delete a space separated list of filters
+
+Usage: ``debugfilter unset [id...]``
+
+disable
+-------
+Disable a space separated list of filters but keep it in the filter list
+
+Usage: ``debugfilter disable [id...]``
+
+enable
+------
+Enable a space sperate list of filters
+
+Usage: ``debugfilter enable [id...]``
+
 .. _hotkeys:
 
 hotkeys

docs/changelog.txt

@@ -37,6 +37,9 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 ================================================================================
 # Future
 
+## New Plugins
+- `debug`: manages runtime debug print category filtering
+
 ## Fixes
 - `fix/dead-units`: fixed script trying to use missing isDiplomat function
 
@@ -56,6 +59,18 @@ changelog.txt uses a syntax similar to RST, with a few special sequences:
 - New functions:
     - ``Units::isDiplomat(unit)``
 - Exposed ``Screen::zoom()`` to C++ (was Lua-only)
+- New classes:
+    - ``Signal<Signature, type_tag>`` to C++ only
+    - ``DebugCategory`` to C++ only (used through new macros)
+    - ``DebugManager`` to C++ only
+- New macros:
+    - ``DBG_DECLARE``
+    - ``DBG_EXTERN``
+    - ``TRACE``
+    - ``DEBUG``
+    - ``INFO``
+    - ``WARN``
+    - ``ERR``
 
 ## Lua
 - ``gui.widgets``: ``List:setChoices`` clones ``choices`` for internal table changes