dissect.cstruct 4.8.dev6__py3-none-any.whl → 4.8.dev8__py3-none-any.whl

dissect/cstruct/utils.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import os
 import pprint
 import string
 import sys
@@ -13,15 +14,29 @@ if TYPE_CHECKING:
     from collections.abc import Iterator
     from typing import Literal
 
-COLOR_RED = "\033[1;31m"
-COLOR_GREEN = "\033[1;32m"
-COLOR_YELLOW = "\033[1;33m"
-COLOR_BLUE = "\033[1;34m"
-COLOR_PURPLE = "\033[1;35m"
-COLOR_CYAN = "\033[1;36m"
-COLOR_WHITE = "\033[1;37m"
-COLOR_NORMAL = "\033[1;0m"
-
+# Regular ANSI colors
+COLOR_RED = "\033[0;31m"
+COLOR_GREEN = "\033[0;32m"
+COLOR_YELLOW = "\033[0;93m"
+COLOR_BLUE = "\033[0;34m"
+COLOR_PURPLE = "\033[0;35m"
+COLOR_CYAN = "\033[0;36m"
+COLOR_WHITE = "\033[0;37m"
+COLOR_BLACK = "\033[0;30m"
+COLOR_GREY = "\033[0;90m"
+
+# Bold ANSI colors
+COLOR_RED_BOLD = "\033[1;31m"
+COLOR_GREEN_BOLD = "\033[1;32m"
+COLOR_YELLOW_BOLD = "\033[1;33m"
+COLOR_BLUE_BOLD = "\033[1;34m"
+COLOR_PURPLE_BOLD = "\033[1;35m"
+COLOR_CYAN_BOLD = "\033[1;36m"
+COLOR_WHITE_BOLD = "\033[1;37m"
+COLOR_BLACK_BOLD = "\033[1;30m"
+COLOR_GREY_BOLD = "\033[1;90m"
+
+# Background ANSI colors
 COLOR_BG_RED = "\033[1;41m\033[1;37m"
 COLOR_BG_GREEN = "\033[1;42m\033[1;37m"
 COLOR_BG_YELLOW = "\033[1;43m\033[1;37m"
@@ -30,6 +45,10 @@ COLOR_BG_PURPLE = "\033[1;45m\033[1;37m"
 COLOR_BG_CYAN = "\033[1;46m\033[1;37m"
 COLOR_BG_WHITE = "\033[1;47m\033[1;30m"
 
+# Reset ANSI codes
+COLOR_CLEAR = "\033[0m"
+COLOR_CLEAR_BOLD = "\033[1;0m"
+
 PRINTABLE = string.digits + string.ascii_letters + string.punctuation + " "
 
 ENDIANNESS_MAP: dict[str, Literal["big", "little"]] = {
@@ -44,20 +63,67 @@ ENDIANNESS_MAP: dict[str, Literal["big", "little"]] = {
 Palette = list[tuple[int, str]]
 
 
-def _hexdump(data: bytes, palette: Palette | None = None, offset: int = 0, prefix: str = "") -> Iterator[str]:
+def _human_colors() -> dict[str, str]:
+    """Generates a dictionary of characters with a human-readable ANSI color they should be in a hexdump.
+
+    Coloring logic implementation derived from HexFriend and ImHex.
+    """
+    # Make all characters not in any rules below light green
+    colors = {chr(char): COLOR_GREEN for char in range(256)}
+
+    # Make all ASCII extended characters yellow
+    for char in colors:
+        if ord(char) & 0x80 == 0:
+            colors[char] = COLOR_YELLOW
+
+    # Make null bytes grey
+    colors["\00"] = COLOR_GREY
+
+    # Make printable ASCII characters bold white (0x32-0x7E)
+    for char in PRINTABLE:
+        colors[char] = COLOR_WHITE_BOLD
+
+    # Make ASCII whitespace characters green bold (0x9, 0xA, 0xB, 0xC, 0xD, 0x20)
+    for char in ("\t", "\n", "\11", "\12", "\r", "\20"):
+        colors[char] = COLOR_GREEN_BOLD
+
+    return colors
+
+
+HUMAN_COLORS = _human_colors()
+
+
+def _hexdump(
+    data: bytes,
+    *,
+    palette: Palette | None = None,
+    offset: int = 0,
+    prefix: str = "",
+    pretty: bool | None = False,
+    autoskip: bool = False,
+) -> Iterator[str]:
     """Hexdump some data.
 
     Args:
         data: Bytes to hexdump.
+        palette: Colorize the hexdump using this color pattern.
         offset: Byte offset of the hexdump.
         prefix: Optional prefix.
-        palette: Colorize the hexdump using this color pattern.
+        pretty: Use pretty colors, mutual exclusive with palette.
+        autoskip: A single '*' replaces NUL-lines in the output.
     """
     if palette:
         palette = palette[::-1]
 
+    # only happy little accidents
+    if pretty and palette:
+        raise ValueError("Cannot use argument 'pretty' in combination with 'palette', please pick one")
+
     remaining = 0
     active = None
+    in_null_run = False
+    in_collapsed_null_run = False
+    last_offset = len(data) - 16
 
     for i in range(0, len(data), 16):
         values = ""
@@ -87,42 +153,80 @@ def _hexdump(data: bytes, palette: Palette | None = None, offset: int = 0, prefi
 
                 if active:
                     values += f"{ord(char):02x}"
-                    chars.append(active + print_char + COLOR_NORMAL)
+                    chars.append(active + print_char + COLOR_CLEAR_BOLD)
                 else:
-                    values += f"{ord(char):02x}"
-                    chars.append(print_char)
+                    if pretty and (color := HUMAN_COLORS.get(char, "")):
+                        values += f"{color}{ord(char):02x}{COLOR_CLEAR}"
+                        chars.append(color + print_char + COLOR_CLEAR)
+                    else:
+                        values += f"{ord(char):02x}"
+                        chars.append(print_char)
 
                 remaining -= 1
                 if remaining == 0:
                     active = None
 
                     if palette is not None:
-                        values += COLOR_NORMAL
+                        values += COLOR_CLEAR_BOLD
 
                 if j == 15 and palette is not None:
-                    values += COLOR_NORMAL
+                    values += COLOR_CLEAR_BOLD
 
             values += " "
             if j == 7:
                 values += " "
 
+        if autoskip and 0 < i < last_offset and data[i : i + 16] == b"\x00" * 16:
+            if in_null_run:
+                if not in_collapsed_null_run:
+                    yield "*"
+                    in_collapsed_null_run = True
+                continue
+
+            # Keep the first interior NUL line visible, collapse from the second onwards.
+            in_null_run = True
+        else:
+            in_null_run = False
+            in_collapsed_null_run = False
+
         chars = "".join(chars)
         yield f"{prefix}{offset + i:08x}  {values:48s}  {chars}"
 
 
 def hexdump(
-    data: bytes, palette: Palette | None = None, offset: int = 0, prefix: str = "", output: str = "print"
+    data: bytes,
+    *,
+    palette: Palette | None = None,
+    offset: int = 0,
+    prefix: str = "",
+    output: str = "print",
+    pretty: bool | None = None,
+    autoskip: bool = False,
 ) -> Iterator[str] | str | None:
     """Hexdump some data.
 
+    Uses colored ANSI output with output type "print" by default. Disable with ``pretty=False``
+    or set the environment variable ``NO_COLOR``.
+
     Args:
         data: Bytes to hexdump.
         palette: Colorize the hexdump using this color pattern.
         offset: Byte offset of the hexdump.
         prefix: Optional prefix.
         output: Output format, can be 'print', 'generator' or 'string'.
+        pretty: Use pretty colors for improved human readability.
+        autoskip: A single '*' replaces NUL-lines in the output.
     """
-    generator = _hexdump(data, palette, offset, prefix)
+    # Enable pretty colors by default if ...
+    if (
+        output == "print"  # the output type is set to 'print'
+        and not palette  # no palette is given (structdump only)
+        and pretty is not False  # pretty was not explicitly set to False
+        and not os.environ.get("NO_COLOR")  # and the environment allows colors
+    ):
+        pretty = True
+
+    generator = _hexdump(data, palette=palette, offset=offset, prefix=prefix, pretty=pretty, autoskip=autoskip)
     if output == "print":
         print("\n".join(generator))
         return None
@@ -139,16 +243,17 @@ def _dumpstruct(
     offset: int,
     color: bool,
     output: str,
+    autoskip: bool,
 ) -> str | None:
     palette = []
     colors = [
-        (COLOR_RED, COLOR_BG_RED),
-        (COLOR_GREEN, COLOR_BG_GREEN),
-        (COLOR_YELLOW, COLOR_BG_YELLOW),
-        (COLOR_BLUE, COLOR_BG_BLUE),
-        (COLOR_PURPLE, COLOR_BG_PURPLE),
-        (COLOR_CYAN, COLOR_BG_CYAN),
-        (COLOR_WHITE, COLOR_BG_WHITE),
+        (COLOR_RED_BOLD, COLOR_BG_RED),
+        (COLOR_GREEN_BOLD, COLOR_BG_GREEN),
+        (COLOR_YELLOW_BOLD, COLOR_BG_YELLOW),
+        (COLOR_BLUE_BOLD, COLOR_BG_BLUE),
+        (COLOR_PURPLE_BOLD, COLOR_BG_PURPLE),
+        (COLOR_CYAN_BOLD, COLOR_BG_CYAN),
+        (COLOR_WHITE_BOLD, COLOR_BG_WHITE),
     ]
     ci = 0
     out = [f"struct {structure.__class__.__name__}:"]
@@ -172,7 +277,7 @@ def _dumpstruct(
             size = structure.__sizes__[field._name]
             palette.append((size, background))
             ci += 1
-            out.append(f"- {foreground}{field._name}{COLOR_NORMAL}: {value}")
+            out.append(f"- {foreground}{field._name}{COLOR_CLEAR_BOLD}: {value}")
         else:
             out.append(f"- {field._name}: {value}")
 
@@ -180,11 +285,11 @@ def _dumpstruct(
 
     if output == "print":
         print()
-        hexdump(data, palette, offset=offset)
+        hexdump(data, palette=palette, offset=offset, autoskip=autoskip)
         print()
         print(out)
     elif output == "string":
-        return f"\n{hexdump(data, palette, offset=offset, output='string')}\n\n{out}"
+        return f"\n{hexdump(data, palette=palette, offset=offset, output='string', autoskip=autoskip)}\n\n{out}"
     return None
 
 
@@ -193,6 +298,7 @@ def dumpstruct(
     data: bytes | None = None,
     offset: int = 0,
     color: bool = True,
+    autoskip: bool = False,
     output: str = "print",
 ) -> str | None:
     """Dump a structure or parsed structure instance.
@@ -203,15 +309,17 @@ def dumpstruct(
         obj: Structure to dump.
         data: Bytes to parse the Structure on, if obj is not a parsed Structure already.
         offset: Byte offset of the hexdump.
+        color: Colorize the hexdump and structure output.
+        autoskip: A single '*' replaces NUL-lines in the output.
         output: Output format, can be 'print' or 'string'.
     """
     if output not in ("print", "string"):
         raise ValueError(f"Invalid output argument: {output!r} (should be 'print' or 'string').")
 
     if isinstance(obj, Structure):
-        return _dumpstruct(obj, obj.dumps(), offset, color, output)
+        return _dumpstruct(obj, obj.dumps(), offset, color, output, autoskip)
     if issubclass(obj, Structure) and data is not None:
-        return _dumpstruct(obj(data), data, offset, color, output)
+        return _dumpstruct(obj(data), data, offset, color, output, autoskip)
     raise ValueError("Invalid arguments")
 
 

{dissect_cstruct-4.8.dev6.dist-info → dissect_cstruct-4.8.dev8.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dissect.cstruct
-Version: 4.8.dev6
+Version: 4.8.dev8
 Summary: A Dissect module implementing a parser for C-like structures: structure parsing in Python made easy
 Author-email: Dissect Team <dissect@fox-it.com>
 License-Expression: Apache-2.0

{dissect_cstruct-4.8.dev6.dist-info → dissect_cstruct-4.8.dev8.dist-info}/RECORD

@@ -5,7 +5,7 @@ dissect/cstruct/cstruct.py,sha256=1lHbxZwj5x2EmmXLR0sJlp-wQqaTtd_ht1lvwit0KtQ,19
 dissect/cstruct/exceptions.py,sha256=SX05-_HqQn8lYC7SBHv5OrYEepYRMNmRiIzVPW8bvMQ,330
 dissect/cstruct/expression.py,sha256=mf5GFGLAn_2Tz3QK86Yqoi317l8cjMcffBKzP2STE6M,10841
 dissect/cstruct/parser.py,sha256=Mk8QbkDov_xfauZnp2MqUmFGOPZlp7O2rSLYbB9S3g4,24550
-dissect/cstruct/utils.py,sha256=6cU1QHTZnHXQaPoxMH93ELkwIIUgYw-TtxieEcVvYvw,10537
+dissect/cstruct/utils.py,sha256=jSWZY8AWoLHF1W9ix-7EH2eI7pTHzLfnSfQHWH1qgKM,14190
 dissect/cstruct/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 dissect/cstruct/tools/stubgen.py,sha256=wvl07h3VnJZWe9ygX4QMxjEH1ZcWaI_6_pSdAJoOEXk,7820
 dissect/cstruct/types/__init__.py,sha256=6P71Pu94Dv7RNjZpDZ19pqzx-G0QzmQw4q0-3zWALso,911
@@ -20,10 +20,10 @@ dissect/cstruct/types/pointer.py,sha256=PqeJOoNBUfMd5uO2kpF6OHeW7Q6R1N1W1V4q1Mak
 dissect/cstruct/types/structure.py,sha256=I9LVeZ81rNE5GDT6wxpUL-PqMO31Ae6TVLLzTGyd6mM,33012
 dissect/cstruct/types/void.py,sha256=Gvh0HqI6jQSj2uesdo3J8-G41brWCz8pmP16l8xTBxE,1074
 dissect/cstruct/types/wchar.py,sha256=N9Y_XX2_hZEe2DwepJjxsB6xuRJ6zINRalcUofR59kY,2608
-dissect_cstruct-4.8.dev6.dist-info/licenses/COPYRIGHT,sha256=H-18RXfshdH9AdHwW2eO1Xa-5s6tY5eipHh5c0whDu4,316
-dissect_cstruct-4.8.dev6.dist-info/licenses/LICENSE,sha256=PhUqiw6jAh2KbBdVRPBq_hfAvfcTBin7nZ3CK7NQbTM,11341
-dissect_cstruct-4.8.dev6.dist-info/METADATA,sha256=pY7CiLwA8RVVBdf6iR3YhgUST9cRXtAT2-nGhWQ2tAQ,9255
-dissect_cstruct-4.8.dev6.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-dissect_cstruct-4.8.dev6.dist-info/entry_points.txt,sha256=z53zqZqwD2OLrAkRwrP4wTeiU9CQe7xrMly0T2c0_wQ,71
-dissect_cstruct-4.8.dev6.dist-info/top_level.txt,sha256=Mn-CQzEYsAbkxrUI0TnplHuXnGVKzxpDw_po_sXpvv4,8
-dissect_cstruct-4.8.dev6.dist-info/RECORD,,
+dissect_cstruct-4.8.dev8.dist-info/licenses/COPYRIGHT,sha256=H-18RXfshdH9AdHwW2eO1Xa-5s6tY5eipHh5c0whDu4,316
+dissect_cstruct-4.8.dev8.dist-info/licenses/LICENSE,sha256=PhUqiw6jAh2KbBdVRPBq_hfAvfcTBin7nZ3CK7NQbTM,11341
+dissect_cstruct-4.8.dev8.dist-info/METADATA,sha256=LpS2_xD11bTw0F2YOz0X9ZWNDgptmNd_FcgzHnrR8nI,9255
+dissect_cstruct-4.8.dev8.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+dissect_cstruct-4.8.dev8.dist-info/entry_points.txt,sha256=z53zqZqwD2OLrAkRwrP4wTeiU9CQe7xrMly0T2c0_wQ,71
+dissect_cstruct-4.8.dev8.dist-info/top_level.txt,sha256=Mn-CQzEYsAbkxrUI0TnplHuXnGVKzxpDw_po_sXpvv4,8
+dissect_cstruct-4.8.dev8.dist-info/RECORD,,