feat: add quick to_dict() method to all objects

Author: MrIndeciso

SKILL.md

@@ -290,6 +290,18 @@ print(player.hexdump())
 
 Struct hexdumps annotate lines with field names. Primitive hexdumps show raw bytes.
 
+### Dict / JSON Export
+
+```python
+point = point_t.from_bytes(memory)
+point.to_dict()  # {"x": 10, "y": 20}
+
+import json
+json.dumps(entity.to_dict())  # nested structs produce nested dicts
+```
+
+`to_dict()` works on all types: primitives return their value, structs return `{name: value}` dicts, arrays return lists, unions return variant values, enums return their int value.
+
 ### Freeze / Diff / Reset
 
 ```python

docs/basics/structs.md

@@ -104,6 +104,31 @@ print(repr(header))
 # }
 ```
 
+## Dict / JSON Export
+
+Use `to_dict()` to get a JSON-serializable dictionary of field names to values:
+
+```python
+header = header_t.from_bytes(data)
+print(header.to_dict())
+# {"magic": 3735928559, "version": 1, "size": 4096}
+```
+
+Nested structs produce nested dicts, arrays become lists:
+
+```python
+import json
+
+rect = rect_t.from_bytes(data)
+print(json.dumps(rect.to_dict(), indent=2))
+# {
+#   "origin": {"x": 0, "y": 0},
+#   "size": {"x": 0, "y": 0}
+# }
+```
+
+`to_dict()` also works on individual fields — primitives return their Python value, enums return their integer value.
+
 ## Equality
 
 Two struct instances are equal if they have the same members with the same values:

libdestruct/common/array/array_impl.py

@@ -60,6 +60,10 @@ def set(self: array_impl, _: list[obj]) -> None:
         """Set the array from a list."""
         raise NotImplementedError("Cannot set items in an array.")
 
+    def to_dict(self: array_impl) -> list[object]:
+        """Return a JSON-serializable list of element values."""
+        return [elem.to_dict() for elem in self]
+
     def to_bytes(self: array_impl) -> bytes:
         """Return the serialized representation of the array."""
         return b"".join(bytes(x) for x in self)

libdestruct/common/obj.py

@@ -181,6 +181,10 @@ def __ge__(self: obj, other: object) -> bool:
             return NotImplemented
         return pair[0] >= pair[1]
 
+    def to_dict(self: obj) -> object:
+        """Return a JSON-serializable representation of the object."""
+        return self.value
+
     def hexdump(self: obj) -> str:
         """Return a hex dump of this object's bytes."""
         address = self.address if not self._frozen else 0

libdestruct/common/struct/struct_impl.py

@@ -211,6 +211,10 @@ def to_bytes(self: struct_impl) -> bytes:
         """Return the serialized representation of the struct."""
         return b"".join(member.to_bytes() for member in self._members.values())
 
+    def to_dict(self: struct_impl) -> dict[str, object]:
+        """Return a JSON-serializable dict of field names to values."""
+        return {name: member.to_dict() for name, member in self._members.items()}
+
     def hexdump(self: struct_impl) -> str:
         """Return a hex dump of this struct's bytes with field annotations."""
         annotations = {}

libdestruct/common/union/union.py

@@ -66,6 +66,14 @@ def _set(self: union, value: object) -> None:
             raise RuntimeError("Cannot set the value of a union without an active variant.")
         self._variant._set(value)
 
+    def to_dict(self: union) -> object:
+        """Return a JSON-serializable representation of the union."""
+        if self._variant is not None:
+            return self._variant.to_dict()
+        if self._variants:
+            return {name: v.to_dict() for name, v in self._variants.items()}
+        return None
+
     def to_bytes(self: union) -> bytes:
         """Return the full union-sized region as bytes."""
         if self._frozen_bytes is not None:

test/scripts/to_dict_test.py

@@ -0,0 +1,135 @@
+#
+# This file is part of libdestruct (https://github.com/mrindeciso/libdestruct).
+# Copyright (c) 2026 Roberto Alessandro Bertolini. All rights reserved.
+# Licensed under the MIT license. See LICENSE file in the project root for details.
+#
+
+import json
+import struct as pystruct
+import unittest
+from enum import IntEnum
+
+from libdestruct import (
+    array_of,
+    c_float,
+    c_int,
+    c_long,
+    c_str,
+    enum_of,
+    inflater,
+    ptr_to,
+    struct,
+)
+from libdestruct.common.enum import enum
+from libdestruct.common.union import tagged_union, union, union_of
+
+
+class ToDictTest(unittest.TestCase):
+    def test_primitive_to_dict(self):
+        """Primitive to_dict returns its Python value."""
+        x = c_int.from_bytes(b"\x2a\x00\x00\x00")
+        self.assertEqual(x.to_dict(), 42)
+
+    def test_struct_to_dict(self):
+        """Struct to_dict returns a dict of field names to values."""
+        class point_t(struct):
+            x: c_int
+            y: c_int
+
+        memory = pystruct.pack("<ii", 10, 20)
+        point = point_t.from_bytes(memory)
+        result = point.to_dict()
+        self.assertEqual(result, {"x": 10, "y": 20})
+
+    def test_nested_struct_to_dict(self):
+        """Nested struct produces nested dicts."""
+        class vec2(struct):
+            x: c_int
+            y: c_int
+
+        class entity_t(struct):
+            id: c_int
+            pos: vec2
+
+        memory = pystruct.pack("<iii", 1, 10, 20)
+        entity = entity_t.from_bytes(memory)
+        result = entity.to_dict()
+        self.assertEqual(result, {"id": 1, "pos": {"x": 10, "y": 20}})
+
+    def test_struct_with_ptr_to_dict(self):
+        """Pointer field returns its address as int."""
+        class data_t(struct):
+            value: c_int
+            ref: c_long
+
+        memory = pystruct.pack("<iq", 42, 0x1000)
+        data = data_t.from_bytes(memory)
+        result = data.to_dict()
+        self.assertEqual(result, {"value": 42, "ref": 0x1000})
+
+    def test_struct_with_enum_to_dict(self):
+        """Enum field returns its integer value."""
+        class Color(IntEnum):
+            RED = 0
+            GREEN = 1
+            BLUE = 2
+
+        class pixel_t(struct):
+            color: enum = enum_of(Color)
+            alpha: c_int
+
+        memory = pystruct.pack("<ii", 1, 255)
+        pixel = pixel_t.from_bytes(memory)
+        result = pixel.to_dict()
+        self.assertEqual(result["color"], 1)
+        self.assertEqual(result["alpha"], 255)
+
+    def test_struct_with_array_to_dict(self):
+        """Array field returns a list of values."""
+        class packet_t(struct):
+            data: c_int = array_of(c_int, 3)
+
+        memory = pystruct.pack("<iii", 10, 20, 30)
+        pkt = packet_t.from_bytes(memory)
+        result = pkt.to_dict()
+        self.assertEqual(result, {"data": [10, 20, 30]})
+
+    def test_struct_with_tagged_union_to_dict(self):
+        """Tagged union returns the active variant's value."""
+        class msg_t(struct):
+            type: c_int
+            payload: union = tagged_union("type", {0: c_int, 1: c_float})
+
+        memory = pystruct.pack("<ii", 0, 42)
+        msg = msg_t.from_bytes(memory)
+        result = msg.to_dict()
+        self.assertEqual(result["type"], 0)
+        self.assertEqual(result["payload"], 42)
+
+    def test_struct_with_plain_union_to_dict(self):
+        """Plain union returns a dict of all variant values."""
+        class packet_t(struct):
+            data: union = union_of({"i": c_int, "f": c_float})
+
+        memory = pystruct.pack("<i", 42)
+        pkt = packet_t.from_bytes(memory)
+        result = pkt.to_dict()
+        self.assertIn("i", result["data"])
+        self.assertIn("f", result["data"])
+        self.assertEqual(result["data"]["i"], 42)
+
+    def test_to_dict_is_json_serializable(self):
+        """to_dict output can be passed to json.dumps."""
+        class point_t(struct):
+            x: c_int
+            y: c_int
+
+        memory = pystruct.pack("<ii", 10, 20)
+        point = point_t.from_bytes(memory)
+        result = json.dumps(point.to_dict())
+        self.assertEqual(json.loads(result), {"x": 10, "y": 20})
+
+    def test_float_to_dict(self):
+        """Float to_dict returns its Python float value."""
+        f = c_float.from_bytes(pystruct.pack("<f", 3.14))
+        self.assertAlmostEqual(f.to_dict(), 3.14, places=2)