dissect.cstruct 4.8.dev6__tar.gz → 4.8.dev8__tar.gz

{dissect_cstruct-4.8.dev6 → dissect_cstruct-4.8.dev8}/PKG-INFO

@@ -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 → dissect_cstruct-4.8.dev8}/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 → dissect_cstruct-4.8.dev8}/dissect.cstruct.egg-info/PKG-INFO

@@ -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 → dissect_cstruct-4.8.dev8}/tests/test_utils.py

@@ -14,7 +14,7 @@ if TYPE_CHECKING:
 
 
 def test_hexdump(capsys: pytest.CaptureFixture) -> None:
-    utils.hexdump(b"\x00" * 16)
+    utils.hexdump(b"\x00" * 16, pretty=False)
     captured = capsys.readouterr()
     assert captured.out == "00000000  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00   ................\n"
 
@@ -30,6 +30,137 @@ def test_hexdump(capsys: pytest.CaptureFixture) -> None:
         utils.hexdump("b\x00", output="str")
 
 
+def test_hexdump_pretty(capsys: pytest.CaptureFixture) -> None:
+    """Check if we can create a pretty hexdump."""
+    c = utils.COLOR_CLEAR
+    g = utils.COLOR_GREY
+    w = utils.COLOR_WHITE_BOLD
+    y = utils.COLOR_YELLOW
+
+    utils.hexdump((b"\x00" * 5) + b"\x01\x02\x03abc" + (b"\x00" * 5), pretty=True)
+    captured = capsys.readouterr()
+    assert (
+        captured.out
+        == "00000000  "
+        + (f"{g}00{c} " * 5)
+        + f"{y}01{c} {y}02{c} {y}03{c}  {w}61{c} {w}62{c} {w}63{c} "
+        + (f"{g}00{c} " * 5)
+        + "  "
+        + (f"{g}.{c}" * 5)
+        + f"{y}.{c}{y}.{c}{y}.{c}{w}a{c}{w}b{c}{w}c{c}"
+        + (f"{g}.{c}" * 5)
+        + "\n"
+    )
+
+
+def test_hexdump_autoskip_collapses_middle_null_run() -> None:
+    """Keep first interior NUL line, then collapse the rest of that run to '*'."""
+    # Layout: [A data line] [3 NUL lines] [B data line]
+    # Expected: [A line] [first NUL line] [*] [B line] = 4 lines
+    data = (b"A" * 16) + (b"\x00" * 48) + (b"B" * 16)
+
+    out = utils.hexdump(data, output="string", pretty=False, autoskip=True)
+    assert out is not None
+
+    lines = out.splitlines()
+    assert len(lines) == 4
+    assert lines[0].startswith("00000000")  # A line
+    assert lines[1].startswith("00000010")  # First NUL line is kept
+    assert lines[2] == "*"  # Remaining NUL lines collapsed
+    assert lines[3].startswith("00000040")  # B line
+
+
+def test_hexdump_autoskip_keeps_edge_null_lines() -> None:
+    """Do not collapse first/last hexdump lines even when they are all NUL bytes."""
+    # Layout: [3 NUL lines]
+    # Expected: all lines are kept (only one interior line, so nothing is repeated there)
+    data = b"\x00" * 48
+
+    out = utils.hexdump(data, output="string", pretty=False, autoskip=True)
+    assert out is not None
+
+    lines = out.splitlines()
+    assert len(lines) == 3
+    assert lines[0].startswith("00000000")  # First line kept (edge)
+    assert lines[1].startswith("00000010")  # Single interior NUL line is kept
+    assert lines[2].startswith("00000020")  # Last line kept (edge)
+
+
+def test_hexdump_autoskip_separate_null_runs() -> None:
+    """Emit one '*' per interior NUL run, after keeping each run's first interior NUL line."""
+    # Layout: [A data] [2 NUL lines] [B data] [2 NUL lines] [C data]
+    # Expected: [A line] [NUL line] [*] [B line] [NUL line] [*] [C line] = 7 lines
+    data = (b"A" * 16) + (b"\x00" * 32) + (b"B" * 16) + (b"\x00" * 32) + (b"C" * 16)
+
+    out = utils.hexdump(data, output="string", pretty=False, autoskip=True)
+    assert out is not None
+
+    lines = out.splitlines()
+    assert len(lines) == 7
+    assert lines[0].startswith("00000000")  # A line
+    assert lines[1].startswith("00000010")  # First NUL line of first run kept
+    assert lines[2] == "*"  # Remaining NUL lines of first run collapsed
+    assert lines[3].startswith("00000030")  # B line
+    assert lines[4].startswith("00000040")  # First NUL line of second run kept
+    assert lines[5] == "*"  # Remaining NUL lines of second run collapsed
+    assert lines[6].startswith("00000060")  # C line
+
+
+def test_hexdump_autoskip_single_interior_null_line_is_not_collapsed() -> None:
+    """Keep a single interior all-NUL line visible when autoskip is enabled."""
+    # Layout: [A data line] [1 NUL line] [B data line]
+    # Expected: [A line] [NUL line] [B line] = 3 lines (no repeated interior NUL line)
+    data = (b"A" * 16) + (b"\x00" * 16) + (b"B" * 16)
+
+    out = utils.hexdump(data, output="string", pretty=False, autoskip=True)
+    assert out is not None
+
+    lines = out.splitlines()
+    assert len(lines) == 3
+    assert lines[0].startswith("00000000")  # A line
+    assert lines[1].startswith("00000010")  # Single NUL line is kept
+    assert lines[2].startswith("00000020")  # B line
+
+
+def test_hexdump_autoskip_false_does_not_collapse() -> None:
+    """Keep all lines expanded and never emit '*' when autoskip is disabled."""
+    # Layout: [A data line] [3 NUL lines] [B data line]
+    # Expected: [A line] [NUL line] [NUL line] [NUL line] [B line] = 5 lines (no * when disabled)
+    data = (b"A" * 16) + (b"\x00" * 48) + (b"B" * 16)
+
+    out = utils.hexdump(data, output="string", pretty=False, autoskip=False)
+    assert out is not None
+
+    lines = out.splitlines()
+    assert len(lines) == 5
+    assert all(line != "*" for line in lines)  # No * when autoskip disabled
+    assert lines[0].startswith("00000000")  # A line
+    assert lines[1].startswith("00000010")  # First NUL line (expanded)
+    assert lines[2].startswith("00000020")  # Second NUL line (expanded)
+    assert lines[3].startswith("00000030")  # Third NUL line (expanded)
+    assert lines[4].startswith("00000040")  # B line
+
+
+def test_hexdump_pretty_print_conditions(capsys: pytest.CaptureFixture, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Test if we respec the ``NO_COLOR`` environment variable and ``pretty=False`` argument."""
+    # Test regular print output behavior
+    utils.hexdump(b"\x00" * 16)
+    captured = capsys.readouterr()
+    assert captured.out.startswith("00000000  \x1b[0;90m00")
+
+    # Test explicit disable using NO_COLOR
+    with monkeypatch.context() as m:
+        m.setenv("NO_COLOR", "1")
+        utils.hexdump(b"\x00" * 16)
+        captured = capsys.readouterr()
+        assert captured.out.startswith("00000000  00")
+
+    # Test explicit disable using pretty=False
+    utils.hexdump(b"\x00" * 16, pretty=False)
+    captured = capsys.readouterr()
+    assert captured.out.startswith("00000000  00")
+
+
 def test_dumpstruct(cs: cstruct, capsys: pytest.CaptureFixture, compiled: bool) -> None:
     cdef = """
     struct test {