docs: add basic project documentation

Author: MrIndeciso

docs/advanced/c_parser.md

@@ -0,0 +1,138 @@
+# C Struct Parser
+
+libdestruct can parse C struct definitions directly and convert them into usable Python types. This is powered by [pycparser](https://github.com/eliben/pycparser).
+
+## Basic Usage
+
+```python
+from libdestruct.c.struct_parser import definition_to_type
+
+player_t = definition_to_type("""
+    struct player_t {
+        int health;
+        unsigned int score;
+        long experience;
+    };
+""")
+
+memory = b"\x64\x00\x00\x00\xe8\x03\x00\x00\x39\x05\x00\x00\x00\x00\x00\x00"
+player = player_t.from_bytes(memory)
+
+print(player.health.value)      # 100
+print(player.score.value)       # 1000
+print(player.experience.value)  # 1337
+```
+
+## Supported C Types
+
+The parser recognizes these C type specifiers:
+
+| C Type | Maps to |
+|---|---|
+| `int` | `c_int` |
+| `unsigned int` | `c_uint` |
+| `long` | `c_long` |
+| `unsigned long` | `c_ulong` |
+| `char` | `c_char` |
+
+Type names are normalized — `unsigned int`, `uint`, and `unsigned` all map to `c_uint`.
+
+## Pointers
+
+Single, double, and triple pointers are supported:
+
+```python
+t = definition_to_type("""
+    struct test {
+        int *p;
+        int **pp;
+        int ***ppp;
+    };
+""")
+```
+
+Self-referential pointers are automatically detected:
+
+```python
+node_t = definition_to_type("""
+    struct node {
+        int value;
+        struct node *next;
+    };
+""")
+```
+
+## Arrays
+
+Fixed-size arrays are converted to `array_of()`:
+
+```python
+t = definition_to_type("""
+    struct buffer {
+        int data[16];
+    };
+""")
+```
+
+## Nested Structs
+
+Define multiple structs in a single definition:
+
+```python
+t = definition_to_type("""
+    struct point {
+        int x;
+        int y;
+    };
+
+    struct rect {
+        struct point origin;
+        struct point size;
+    };
+""")
+```
+
+The last struct in the definition is returned. All previous structs are cached and available for forward references.
+
+## Include Directives
+
+The parser supports `#include` directives by running the C preprocessor:
+
+```python
+t = definition_to_type("""
+    #include <stdint.h>
+
+    struct packet {
+        int type;
+        unsigned long length;
+    };
+""")
+```
+
+!!! warning
+    Include expansion requires a C preprocessor (`cpp`) to be available on your system.
+
+## GCC Attributes
+
+`__attribute__((...))` annotations are automatically stripped before parsing:
+
+```python
+t = definition_to_type("""
+    struct __attribute__((packed)) data {
+        int x;
+        int y;
+    };
+""")
+```
+
+## Caching
+
+Parsed struct definitions are cached globally. Parsing the same struct name twice returns the cached version:
+
+```python
+# First call parses
+t1 = definition_to_type("struct foo { int x; };")
+
+# Second call with same name returns cached type
+t2 = definition_to_type("struct foo { int x; };")
+```

docs/advanced/forward_refs.md

@@ -0,0 +1,85 @@
+# Forward References
+
+Forward references allow structs to reference types that haven't been fully defined yet — most commonly, the struct itself. This is essential for recursive data structures like linked lists and trees.
+
+## The `ptr["TypeName"]` Syntax
+
+Use a string inside `ptr[...]` to reference a type by name:
+
+```python
+from libdestruct import struct, c_int, ptr
+
+class Node(struct):
+    val: c_int
+    next: ptr["Node"]
+```
+
+At inflation time, the string `"Node"` is resolved to the actual `Node` class. This works because Python's `from __future__ import annotations` (used internally by libdestruct) defers annotation evaluation.
+
+## The `ptr_to_self` Shortcut
+
+For the common case of a pointer to the enclosing struct, use `ptr_to_self`:
+
+```python
+from libdestruct import struct, c_int, ptr_to_self
+
+class Node(struct):
+    val: c_int
+    next: ptr_to_self
+```
+
+This is equivalent to `ptr["Node"]` but doesn't require you to spell out the type name.
+
+## Linked List Example
+
+```python
+from libdestruct import struct, c_int, ptr, inflater
+
+class Node(struct):
+    val: c_int
+    next: ptr["Node"]
+
+# Build a two-node list in memory
+# Node layout: c_int(4) + ptr(8) = 12 bytes
+memory = bytearray(24)
+
+import struct as pystruct
+# Node 0 at offset 0
+memory[0:4] = pystruct.pack("<i", 10)
+memory[4:12] = pystruct.pack("<q", 12)   # next -> offset 12
+
+# Node 1 at offset 12
+memory[12:16] = pystruct.pack("<i", 20)
+memory[16:24] = pystruct.pack("<q", 0)   # next -> null
+
+lib = inflater(memory)
+head = lib.inflate(Node, 0)
+
+print(head.val.value)                        # 10
+print(head.next.unwrap().val.value)          # 20
+print(head.next.unwrap().next.try_unwrap())  # None
+```
+
+## Tree Example
+
+```python
+from libdestruct import struct, c_uint, ptr
+
+class TreeNode(struct):
+    data: c_uint
+    left: ptr["TreeNode"]
+    right: ptr["TreeNode"]
+```
+
+## How It Works
+
+When libdestruct encounters a `ptr["TypeName"]` annotation:
+
+1. It stores the string reference during struct class creation
+2. At inflation time, it resolves the string against all known struct types
+3. The resolved type is used as the pointer's wrapper type
+
+This means the referenced type must be defined before the struct is inflated, but not necessarily before it is declared.
+
+!!! info
+    Forward references are resolved through the `TypeRegistry` at inflation time. If the referenced type is not found, an error is raised.

docs/advanced/freeze_diff.md

@@ -0,0 +1,117 @@
+# Freeze, Diff & Reset
+
+libdestruct supports snapshotting values for change tracking. This is useful when you want to detect what changed in memory between two points in time.
+
+## Freezing
+
+Call `freeze()` to snapshot the current value:
+
+```python
+from libdestruct import c_int, inflater
+
+memory = bytearray(4)
+lib = inflater(memory)
+x = lib.inflate(c_int, 0)
+
+x.value = 42
+x.freeze()
+```
+
+Once frozen, the object remembers its value at the time of the freeze. Further reads still return the live value from memory, but writes are blocked:
+
+```python
+# Writing to a frozen object raises ValueError
+try:
+    x.value = 99
+except ValueError:
+    print("Cannot write to frozen object")
+```
+
+## Diffing
+
+Use `diff()` to compare the frozen value with the current live value:
+
+```python
+x.value = 42
+x.freeze()
+
+# Something changes the underlying memory
+memory[0:4] = (100).to_bytes(4, "little")
+
+frozen_val, current_val = x.diff()
+print(f"Was: {frozen_val}, Now: {current_val}")
+# Was: 42, Now: 100
+```
+
+!!! note
+    `diff()` only works on frozen objects. It returns a tuple of `(frozen_value, current_value)`.
+
+## Resetting
+
+Call `reset()` to restore the memory to the frozen value:
+
+```python
+x.reset()
+print(x.value)  # 42 (restored to frozen value)
+```
+
+## Updating
+
+Call `update()` to re-freeze with the current live value, discarding the old snapshot:
+
+```python
+x.update()
+# The frozen value is now whatever is currently in memory
+```
+
+## Freezing Structs
+
+When you freeze a struct, all its members are frozen recursively:
+
+```python
+from libdestruct import struct, c_int, inflater
+
+class pair_t(struct):
+    a: c_int
+    b: c_int
+
+memory = bytearray(8)
+lib = inflater(memory)
+pair = lib.inflate(pair_t, 0)
+
+pair.a.value = 10
+pair.b.value = 20
+
+pair.freeze()
+
+# Both members are now frozen
+try:
+    pair.a.value = 999
+except ValueError:
+    print("Frozen!")
+```
+
+## Workflow Example
+
+A typical workflow for detecting changes:
+
+```python
+# 1. Inflate the struct
+state = lib.inflate(game_state_t, addr)
+
+# 2. Freeze the current state
+state.freeze()
+
+# 3. Let the program run (memory changes externally)
+# ...
+
+# 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}")
+
+# 5. Optionally reset to the frozen state
+state.reset()
+```