test/docs: automatically check doc snippets to verity their correctness

MrIndeciso · MrIndeciso · commit f71009a5a9ad · 2026-04-01T13:08:53.000-05:00
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -39,7 +39,7 @@ jobs:
       run: |
         python -m pip install --upgrade pip
         python -m pip install --upgrade wheel build
-        python -m pip install pwntools pytest libdebug
+        python -m pip install pwntools pytest libdebug mktestdocs
 
     - name: Install library
       run: |
diff --git a/SKILL.md b/SKILL.md
@@ -197,7 +197,7 @@ Legacy syntax with `array_of()` is still supported:
 ```python
 class packet_t(struct):
     length: c_int
-    data: array_of(c_int, 8)
+    data: array = array_of(c_int, 8)
 ```
 
 Access array elements:
diff --git a/docs/advanced/alignment.md b/docs/advanced/alignment.md
@@ -7,7 +7,7 @@ You can opt into natural alignment (matching standard C struct layout) by settin
 ## Enabling Alignment
 
 ```python
-from libdestruct import struct, c_char, c_int, c_long, size_of
+from libdestruct import struct, c_char, c_int, c_long, c_short, size_of, alignment_of
 
 class packed_t(struct):
     a: c_char
diff --git a/docs/advanced/bitfields.md b/docs/advanced/bitfields.md
@@ -7,7 +7,7 @@ Bitfields let you pack multiple values into a single integer, just like C bitfie
 Use `bitfield_of(backing_type, bit_width)` as a struct field descriptor:
 
 ```python
-from libdestruct import struct, c_uint, bitfield_of
+from libdestruct import struct, c_uint, c_long, bitfield_of
 
 class flags_t(struct):
     read: c_uint = bitfield_of(c_uint, 1)
diff --git a/docs/advanced/freeze_diff.md b/docs/advanced/freeze_diff.md
@@ -32,6 +32,10 @@ except ValueError:
 Use `diff()` to compare the frozen value with the current live value:
 
 ```python
+memory = bytearray(4)
+lib = inflater(memory)
+x = lib.inflate(c_int, 0)
+
 x.value = 42
 x.freeze()
 
@@ -96,22 +100,35 @@ except ValueError:
 A typical workflow for detecting changes:
 
 ```python
+class game_state_t(struct):
+    health: c_int
+    score: c_int
+    level: c_int
+
+memory = bytearray(12)
+lib = inflater(memory)
+
 # 1. Inflate the struct
-state = lib.inflate(game_state_t, addr)
+state = lib.inflate(game_state_t, 0)
 
 # 2. Freeze the current state
+state.health.value = 100
+state.score.value = 500
+state.level.value = 3
 state.freeze()
 
-# 3. Let the program run (memory changes externally)
-# ...
+# 3. Something changes the underlying memory
+memory[4:8] = (9999).to_bytes(4, "little")  # score changed
 
 # 4. Check what changed
 for name in ["health", "score", "level"]:
     member = getattr(state, name)
     old, new = member.diff()
     if old != new:
         print(f"{name}: {old} -> {new}")
+# score: 500 -> 9999
 
 # 5. Optionally reset to the frozen state
 state.reset()
+print(state.score.value)  # 500 (restored)
 ```
diff --git a/docs/advanced/offset.md b/docs/advanced/offset.md
@@ -102,14 +102,5 @@ class example_t(struct):
     items: Annotated[array[c_int, 4], offset(0x10)]
 ```
 
-With the legacy syntax, `offset()` can be combined with `Field` attributes using a tuple:
-
-```python
-from libdestruct.common.field import Field
-
-class example_t(struct):
-    data: c_int = (Field(), offset(8))
-```
-
 !!! note
-    When using tuples of attributes, only one `Field` is allowed per annotation. Multiple `OffsetAttribute`s are also not typical — use a single `offset()` to set the position.
+    The `Annotated` syntax is preferred for combining offsets with complex types. The legacy default-value syntax also supports offset combined with other field descriptors using a tuple (e.g., `data: c_int = (enum_of(Color), offset(8))`).
diff --git a/docs/advanced/tagged_unions.md b/docs/advanced/tagged_unions.md
@@ -153,6 +153,7 @@ size_of(msg_t)  # 12 (4 + max(4, 8))
 Use the `variant` property to get the active variant object directly:
 
 ```python
+data = pystruct.pack("<i", 0) + pystruct.pack("<i", 42) + b"\x00" * 4
 msg = message_t.from_bytes(data)
 variant_obj = msg.payload.variant  # the raw c_int, c_float, etc.
 ```
@@ -168,7 +169,10 @@ class msg_t(struct):
 
 # type=99 has no matching variant
 memory = pystruct.pack("<i", 99) + b"\x00" * 4
-msg_t.from_bytes(memory)  # raises ValueError
+try:
+    msg_t.from_bytes(memory)
+except ValueError:
+    print("ValueError: unknown discriminator")
 ```
 
 !!! info
diff --git a/docs/basics/arrays.md b/docs/basics/arrays.md
@@ -94,7 +94,7 @@ The legacy `array_of()` syntax is also supported:
 from libdestruct import struct, c_int, array_of
 
 class matrix_row_t(struct):
-    values: array_of(c_int, 4)
+    values: array = array_of(c_int, 4)
 ```
 
 ```python
diff --git a/docs/basics/pointers.md b/docs/basics/pointers.md
@@ -153,27 +153,27 @@ p2 = p_raw + 4   # advances by 4 bytes
 Pointer dereferencing is cached — repeated calls to `unwrap()` or `try_unwrap()` return the same object without re-inflating:
 
 ```python
-r1 = node.next.unwrap()
-r2 = node.next.unwrap()
+r1 = head.next.unwrap()
+r2 = head.next.unwrap()
 assert r1 is r2  # same object
 ```
 
 If the underlying memory changes, call `invalidate()` to clear the cache:
 
 ```python
 # Memory was modified externally
-node.next.invalidate()
-r3 = node.next.unwrap()  # re-inflated from updated memory
+head.next.invalidate()
+r3 = head.next.unwrap()  # re-inflated from updated memory
 ```
 
 Setting the pointer's value automatically invalidates the cache:
 
 ```python
-node.next.value = new_address  # cache cleared automatically
+head.next.value = 24  # cache cleared automatically
 ```
 
 ## Pointer String Representation
 
 ```python
-print(data.next.to_str())  # "c_int@0xc" (or "ptr@0xc" for untyped)
+print(data.next.to_str())  # "c_int@0xc"
 ```
diff --git a/docs/basics/structs.md b/docs/basics/structs.md
@@ -3,10 +3,10 @@
 Structs are the core building block for describing binary layouts. Define a struct by subclassing `struct` and using type annotations:
 
 ```python
-from libdestruct import struct, c_int, c_long
+from libdestruct import struct, c_int, c_uint, c_long
 
 class header_t(struct):
-    magic: c_int
+    magic: c_uint
     version: c_int
     size: c_long
 ```
@@ -40,6 +40,10 @@ print(f"size: {header.size.value}")           # size: 4096
 Each struct field is an `obj` instance. Use `.value` to read or write the underlying value:
 
 ```python
+memory = bytearray(16)
+lib = inflater(memory)
+header = lib.inflate(header_t, 0)
+
 header.magic.value = 0xcafebabe
 print(f"0x{header.magic.value:08x}")  # 0xcafebabe
 ```
diff --git a/docs/basics/types.md b/docs/basics/types.md
@@ -66,7 +66,7 @@ print(x.value)  # 42
 The `size_of()` function returns the size in bytes of any type, instance, or field descriptor:
 
 ```python
-from libdestruct import size_of, c_int, c_long, c_float, ptr, struct, array_of
+from libdestruct import size_of, c_int, c_long, c_float, ptr, struct, array, array_of
 
 size_of(c_int)    # 4
 size_of(c_long)   # 8
diff --git a/docs/memory/inflater.md b/docs/memory/inflater.md
@@ -77,6 +77,15 @@ print(pair.b.value)  # 2
 The inflater lets you inflate multiple objects from different offsets in the same memory:
 
 ```python
+class header_t(struct):
+    magic: c_int
+
+class data_t(struct):
+    value: c_int
+
+class footer_t(struct):
+    checksum: c_int
+
 memory = bytearray(100)
 lib = inflater(memory)
 
diff --git a/libdestruct/common/enum/enum.py b/libdestruct/common/enum/enum.py
@@ -54,7 +54,13 @@ def __init__(
 
     def get(self: enum) -> Enum:
         """Return the value of the enum."""
-        return self.python_enum(self._backing_type.get())
+        raw = self._backing_type.get()
+        if self.lenient:
+            try:
+                return self.python_enum(raw)
+            except ValueError:
+                return raw
+        return self.python_enum(raw)
 
     def _set(self: enum, value: Enum) -> None:
         """Set the value of the enum."""
diff --git a/libdestruct/common/struct/struct_impl.py b/libdestruct/common/struct/struct_impl.py
@@ -284,6 +284,15 @@ def freeze(self: struct_impl) -> None:
 
         super().freeze()
 
+    def reset(self: struct_impl) -> None:
+        """Reset each member to its frozen value."""
+        if not self._frozen:
+            raise RuntimeError("Cannot reset a struct that has not been frozen.")
+
+        members = object.__getattribute__(self, "_members")
+        for member in members.values():
+            member.reset()
+
     def to_str(self: struct_impl, indent: int = 0) -> str:
         """Return a string representation of the struct."""
         name = object.__getattribute__(self, "_struct_name")
diff --git a/test/scripts/doctest_snippets.py b/test/scripts/doctest_snippets.py
@@ -0,0 +1,46 @@
+#
+# 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.
+#
+
+"""Test that all documentation code snippets execute without errors."""
+
+import glob
+import os
+import unittest
+
+from mktestdocs import check_md_file
+
+# Resolve docs/ relative to the repo root, not the working directory.
+_REPO_ROOT = os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+# Files that contain code blocks requiring unavailable system tools
+# (e.g., C preprocessor for #include directives) or intentionally
+# erroneous code (e.g., demonstrating ValueError on invalid input).
+SKIP_FILES = {
+    os.path.join(_REPO_ROOT, "docs/advanced/c_parser.md"),
+}
+
+
+def _make_test(fpath):
+    def test_func(self):
+        check_md_file(fpath, memory=True)
+
+    test_func.__doc__ = f"Snippets in {fpath} execute without errors"
+    return test_func
+
+
+class DocSnippetTest(unittest.TestCase):
+    """Auto-generated tests for documentation code snippets."""
+
+
+for _path in sorted(glob.glob(os.path.join(_REPO_ROOT, "docs/**/*.md"), recursive=True)):
+    if _path in SKIP_FILES:
+        continue
+    _name = "test_" + os.path.relpath(_path, _REPO_ROOT).replace("/", "_").replace(".", "_").replace("-", "_")
+    setattr(DocSnippetTest, _name, _make_test(_path))
+
+
+if __name__ == "__main__":
+    unittest.main()
diff --git a/test/scripts/struct_unit_test.py b/test/scripts/struct_unit_test.py
@@ -230,6 +230,46 @@ class test_t(struct):
             test.a.value = 99
 
 
+class StructResetTest(unittest.TestCase):
+    """Struct reset semantics."""
+
+    def test_struct_reset_restores_members(self):
+        """reset() on a frozen struct should restore all member values."""
+        class test_t(struct):
+            a: c_int
+            b: c_int
+
+        memory = bytearray(8)
+        lib = inflater(memory)
+        test = lib.inflate(test_t, 0)
+        test.a.value = 10
+        test.b.value = 20
+        test.freeze()
+
+        # Modify underlying memory
+        memory[0:4] = (99).to_bytes(4, "little")
+        memory[4:8] = (88).to_bytes(4, "little")
+        # .get() reads live memory; .value returns frozen value
+        self.assertEqual(test.a.get(), 99)
+        self.assertEqual(test.b.get(), 88)
+
+        # Reset should restore frozen values to memory
+        test.reset()
+        self.assertEqual(test.a.get(), 10)
+        self.assertEqual(test.b.get(), 20)
+
+    def test_struct_reset_without_freeze_raises(self):
+        """reset() without freeze should raise."""
+        class test_t(struct):
+            a: c_int
+
+        memory = bytearray(4)
+        lib = inflater(memory)
+        test = lib.inflate(test_t, 0)
+        with self.assertRaises(RuntimeError):
+            test.reset()
+
+
 class ForwardRefPtrTest(unittest.TestCase):
     """Forward reference ptr["Type"] syntax."""
 
