[docs] document 'actions' (#4543)

or at least attempt to
2024-03-31 03:52:29 +02:00
parent bdca01e6e6
commit cf36c576d0
1 changed files with 59 additions and 0 deletions
--- a/docs/configuration.rst
+++ b/docs/configuration.rst
@@ -856,6 +856,65 @@ Description
    for available ``PRAGMA`` statements and further details.


+extractor.*.actions
+-------------------
+Type
+    * ``object`` (`pattern` -> `action`)
+    * ``list`` of ``lists`` with 2 ``strings`` as elements
+Example
+    .. code:: json
+
+        {
+            "error"                   : "status |= 1",
+            "warning:(?i)unable to .+": "exit 127",
+            "info:Logging in as .+"   : "level = debug"
+        }
+
+    .. code:: json
+
+        [
+            ["error"                   , "status |= 1"  ],
+            ["warning:(?i)unable to .+", "exit 127"     ],
+            ["info:Logging in as .+"   , "level = debug"]
+        ]
+
+Description
+    Perform an ``action`` when logging a message matched by ``pattern``.
+
+    ``pattern`` is parsed as severity level (``debug``, ``info``, ``warning``, ``error``, or integer value)
+    followed by an optional `Python Regular Expression <https://docs.python.org/3/library/re.html#regular-expression-syntax>`__
+    separated by a colon ``:``.
+    Using ``*`` as `level` or leaving it empty
+    matches logging messages of all levels
+    (e.g. ``*:<re>`` or ``:<re>``).
+
+    ``action`` is parsed as action type
+    followed by (optional) arguments.
+
+    Supported Action Types:
+
+    ``status``:
+        | Modify job exit status.
+        | Expected syntax is ``<operator> <value>`` (e.g. ``= 100``).
+
+        Supported operators are
+        ``=`` (assignment),
+        ``&`` (bitwise AND),
+        ``|`` (bitwise OR),
+        ``^`` (bitwise XOR).
+    ``level``:
+        | Modify severity level of the current logging message.
+        | Can be one of ``debug``, ``info``, ``warning``, ``error`` or an integer value.
+    ``print``
+        Write argument to stdout.
+    ``restart``:
+        Restart the current extractor run.
+    ``wait``:
+        Stop execution until Enter is pressed.
+    ``exit``:
+        Exit the program with the given argument as exit status.
+
+
 extractor.*.postprocessors
 --------------------------
 Type