documentation

Author: andreax79

README.md

@@ -14,29 +14,36 @@ C-style structs for Python
 Convert C struct/union definitions into Python classes with methods for
 serializing/deserializing.
 
-The usage is very simple: create a class subclassing cstruct.MemCStruct
+The usage is very simple: create a class subclassing
+[`cstruct.MemCStruct`](https://python-cstruct.readthedocs.io/en/latest/api/mem_cstruct/)
 and add a C struct/union definition as a string in the `__def__` field.
 
 The C struct/union definition is parsed at runtime and the struct format string
 is generated. The class offers the method `unpack` for deserializing
 an array of bytes into a Python object and the method `pack` for
 serializing the values into an array of bytes.
 
-[Api Documentation](https://python-cstruct.readthedocs.io/en/latest/)
-
 Install
 -------
 
 ```
 pip install cstruct
 ```
 
+Examples
+--------
+
+* [Read the DOS-type (MBR) partition table](https://python-cstruct.readthedocs.io/en/latest/examples/fdisk/)
+* [Print information about logged uses](https://python-cstruct.readthedocs.io/en/latest/examples/who/)
+* [Flexible Array Member (FAM)](https://python-cstruct.readthedocs.io/en/latest/examples/flexible_array/)
+
+
 Features
 --------
 
 ### Structs
 
-Struct definition subclassing `cstruct.MemCStruct`
+Struct definition subclassing `cstruct.MemCStruct`. Methods can access stuct values as instance variables.
 
 ```python
 class Position(cstruct.MemCStruct):
@@ -47,18 +54,21 @@ class Position(cstruct.MemCStruct):
             unsigned char cyl;
         }
     """
+    @property
+    def lba(self):
+        return (self.cyl * 16 + self.head) * 63 + (self.sector - 1)
 
-pos = Position(head=10, sector=20, cyl=30)
-print(f"head: {pos.head} sector: {pos.sector} cyl: {pos.cyl}")
+pos = Position(cyl=15, head=15, sector=63)
+print(f"head: {pos.head} sector: {pos.sector} cyl: {pos.cyl} lba: {pos.lba}")
 ```
 
-Struct definition using `cstruct.parse`
+Struct definition using `cstruct.parse`.
 
 ```python
 Partition = cstruct.parse("""
-    struct {
-        #define ACTIVE_FLAG         0x80
+    #define ACTIVE_FLAG         0x80
 
+    struct Partition {
         unsigned char status;       /* 0x80 - active */
         struct Position start;
         unsigned char partition_type;
@@ -74,7 +84,7 @@ part.status = cstruct.getdef('ACTIVE_FLAG')
 
 ### Unions
 
-Union definition subclassing `cstruct.MemCStruct`
+Union definition subclassing `cstruct.MemCStruct`.
 
 ```python
 class Data(cstruct.MemCStruct):
@@ -93,7 +103,7 @@ assert data.integer != 2
 
 ### Enums
 
-Enum definition subclassing `cstruct.CEnum`
+Enum definition subclassing `cstruct.CEnum`.
 
 ```python
 class HtmlFont(cstruct.CEnum):
@@ -113,36 +123,17 @@ assert HtmlFont.HTMLFONT_BOLD == 1
 assert HtmlFont.HTMLFONT_ITALIC == 2
 ```
 
-Different supported `__def__` styles:
+Different enum styles are supported in struct/union definitions.
 
 ```c
 enum Type_A a;  // externally defined using CEnum
 enum Type_B {A, B, C} b;
 enum {A, B, C} c;
 ```
 
-```python
-class Type_A(cstruct.CEnum):
-  __size__ = 2
-  __enum__ = """
-    #define SOME_DEFINE 7
-
-    A,
-    B,
-    C = 5,
-    D,
-    E = 7 + SOME_DEFINE
-  """
-
-# this is a nice gimmick that works, but wasn't really planned to be supported
-class Type_C(cstruct.CEnum):
-  A = 0,
-  B = 1,
-  C = 2,
-  D = 3
-```
+### Nested structs/unions
 
-### Nested structures (named/anonymous)
+Nested stucts and unions are supported, both named and anonymous.
 
 ```python
 class Packet(cstruct.MemCStruct):
@@ -204,28 +195,33 @@ pkg.data = [10, 20, 30, 40]
 
 ### Pack and Unpack
 
+A code example illustrating how to use
+[`pack`](https://python-cstruct.readthedocs.io/en/latest/api/abstract/#cstruct.abstract.AbstractCStruct.pack) to pack a structure into binary form.
+
 ```python
-class StructWithEnum(cstruct.MemCStruct):
+class Position(cstruct.MemCStruct):
     __byte_order__ = cstruct.LITTLE_ENDIAN
     __def__ = """
-        struct StructWithEnum {
-            enum HtmlFont font;
-            unsigned int font_size;
+        struct {
+            unsigned char head;
+            unsigned char sector;
+            unsigned char cyl;
         }
     """
 
-# Pack
-s.font = HtmlFont.HTMLFONT_NONE
-s.font_size = 20
-assert s.font == HtmlFont.HTMLFONT_NONE
-assert s.font_size == 20
-packed = s.pack()
-
-# Unpack
-s1 = StructWithEnum()
-s1.unpack(packed)
-assert s1.font == HtmlFont.HTMLFONT_NONE
-assert s1.font_size == 20
+pos = Position(head=10, sector=20, cyl=3)
+packed = pos.pack()
+```
+
+Binary representation can be converted into structure using
+[`unpack`](https://python-cstruct.readthedocs.io/en/latest/api/abstract/#cstruct.abstract.AbstractCStruct.unpack).
+
+```
+pos1 = Position()
+pos1.unpack(packed)
+assert pos1.head == 10
+assert pos1.sector == 20
+assert pos1.cyl == 3
 ```
 
 ### Define, Sizeof, and Eval
@@ -262,7 +258,7 @@ Get structure size:
 cstruct.sizeof(Partition)
 ```
 
-Evaluate C expression:
+Evaluate C expression using [`c_eval`](https://python-cstruct.readthedocs.io/en/latest/api/c_expr/):
 
 ```python
 cstruct.c_eval("A1 / 10")
@@ -294,90 +290,47 @@ class MBR(cstruct.MemCStruct):
     """
 ```
 
-Example
--------
+### Ispect memory
 
-The following program reads the DOS partition information from a disk.
+The [`inspect`](https://python-cstruct.readthedocs.io/en/latest/api/abstract/#cstruct.abstract.AbstractCStruct.inspect) methods displays memory contents in hexadecimal.
 
 ```python
-#!/usr/bin/env python
-import cstruct
-
-class Position(cstruct.MemCStruct):
-    __byte_order__ = cstruct.LITTLE_ENDIAN
-    __def__ = """
-        struct {
-            unsigned char head;
-            unsigned char sector;
-            unsigned char cyl;
-        }
-    """
-
-
-class Partition(cstruct.MemCStruct):
-    __byte_order__ = cstruct.LITTLE_ENDIAN
-    __def__ = """
-        #define ACTIVE_FLAG         0x80
-
-        typedef struct Position Position;
-
-        struct {
-            unsigned char status;       /* 0x80 - active */
-            Position start;
-            unsigned char partition_type;
-            Position end;
-            unsigned int start_sect;    /* starting sector counting from 0 */
-            unsigned int sectors;       /* nr of sectors in partition */
-        }
-    """
-
-    def print_info(self):
-        print(f"bootable: {'Y' if self.status & cstruct.getdef('ACTIVE_FLAG') else 'N'}")
-        print(f"partition_type: {self.partition_type:02X}")
-        print(f"start: head: {self.start.head:X} sectory: {self.start.sector:X} cyl: {self.start.cyl:X}")
-        print(f"end: head: {self.end.head:X} sectory: {self.end.sector:X} cyl: {self.end.cyl:X}")
-        print(f"starting sector: {self.start_sect:08x}")
-        print(f"size MB: {self.sectors / 2 / 1024}")
-
-
-class MBR(cstruct.MemCStruct):
-    __byte_order__ = cstruct.LITTLE_ENDIAN
-    __def__ = """
-        #define MBR_SIZE                    512
-        #define MBR_DISK_SIGNATURE_SIZE       4
-        #define MBR_USUALY_NULLS_SIZE         2
-        #define MBR_SIGNATURE_SIZE            2
-        #define MBR_BOOT_SIGNATURE       0xaa55
-        #define MBR_PARTITIONS_NUM            4
-        #define MBR_PARTITIONS_SIZE  (sizeof(Partition) * MBR_PARTITIONS_NUM)
-        #define MBR_UNUSED_SIZE      (MBR_SIZE - MBR_DISK_SIGNATURE_SIZE - MBR_USUALY_NULLS_SIZE - MBR_PARTITIONS_SIZE - MBR_SIGNATURE_SIZE)
-
-        typedef struct Partition Partition;
-
-        struct {
-            char unused[MBR_UNUSED_SIZE];
-            unsigned char disk_signature[MBR_DISK_SIGNATURE_SIZE];
-            unsigned char usualy_nulls[MBR_USUALY_NULLS_SIZE];
-            Partition partitions[MBR_PARTITIONS_NUM];
-            uint16 signature;
-        }
-    """
+print(mbr.inspect())
+```
 
-    @property
-    def disk_signature_str(self):
-        return "".join(reversed([f"{x:02x}" for x in self.disk_signature]))
-
-    def print_info(self):
-        print(f"disk signature: {self.disk_signature_str}")
-        for i, partition in enumerate(self.partitions):
-            print("")
-            print(f"partition: {i}")
-            partition.print_info()
-
-disk = "mbr"
-with open(disk, "rb") as f:
-    mbr = MBR()
-    mbr.unpack(f)
-    mbr.print_info()
+Output example:
+```
+00000000  eb 48 90 00 00 00 00 00  00 00 00 00 00 00 00 00  |.H..............|
+00000010  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
+00000020  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
+00000030  00 00 00 00 00 00 00 00  00 00 00 00 00 00 03 02  |................|
+00000040  ff 00 00 80 61 cb 04 00  00 08 fa 80 ca 80 ea 53  |....a..........S|
+00000050  7c 00 00 31 c0 8e d8 8e  d0 bc 00 20 fb a0 40 7c  ||..1....... ..@||
+00000060  3c ff 74 02 88 c2 52 be  79 7d e8 34 01 f6 c2 80  |<.t...R.y}.4....|
+00000070  74 54 b4 41 bb aa 55 cd  13 5a 52 72 49 81 fb 55  |tT.A..U..ZRrI..U|
+00000080  aa 75 43 a0 41 7c 84 c0  75 05 83 e1 01 74 37 66  |.uC.A|..u....t7f|
+00000090  8b 4c 10 be 05 7c c6 44  ff 01 66 8b 1e 44 7c c7  |.L...|.D..f..D|.|
+000000a0  04 10 00 c7 44 02 01 00  66 89 5c 08 c7 44 06 00  |....D...f.\..D..|
+000000b0  70 66 31 c0 89 44 04 66  89 44 0c b4 42 cd 13 72  |pf1..D.f.D..B..r|
+000000c0  05 bb 00 70 eb 7d b4 08  cd 13 73 0a f6 c2 80 0f  |...p.}....s.....|
+000000d0  84 f0 00 e9 8d 00 be 05  7c c6 44 ff 00 66 31 c0  |........|.D..f1.|
+000000e0  88 f0 40 66 89 44 04 31  d2 88 ca c1 e2 02 88 e8  |..@f.D.1........|
+000000f0  88 f4 40 89 44 08 31 c0  88 d0 c0 e8 02 66 89 04  |..@.D.1......f..|
+00000100  66 a1 44 7c 66 31 d2 66  f7 34 88 54 0a 66 31 d2  |f.D|f1.f.4.T.f1.|
+00000110  66 f7 74 04 88 54 0b 89  44 0c 3b 44 08 7d 3c 8a  |f.t..T..D.;D.}<.|
+00000120  54 0d c0 e2 06 8a 4c 0a  fe c1 08 d1 8a 6c 0c 5a  |T.....L......l.Z|
+00000130  8a 74 0b bb 00 70 8e c3  31 db b8 01 02 cd 13 72  |.t...p..1......r|
+00000140  2a 8c c3 8e 06 48 7c 60  1e b9 00 01 8e db 31 f6  |*....H|`......1.|
+00000150  31 ff fc f3 a5 1f 61 ff  26 42 7c be 7f 7d e8 40  |1.....a.&B|..}.@|
+00000160  00 eb 0e be 84 7d e8 38  00 eb 06 be 8e 7d e8 30  |.....}.8.....}.0|
+00000170  00 be 93 7d e8 2a 00 eb  fe 47 52 55 42 20 00 47  |...}.*...GRUB .G|
+00000180  65 6f 6d 00 48 61 72 64  20 44 69 73 6b 00 52 65  |eom.Hard Disk.Re|
+00000190  61 64 00 20 45 72 72 6f  72 00 bb 01 00 b4 0e cd  |ad. Error.......|
+000001a0  10 ac 3c 00 75 f4 c3 00  00 00 00 00 00 00 00 00  |..<.u...........|
+000001b0  00 00 00 00 00 00 00 00  40 e2 01 00 00 00 80 00  |........@.......|
+000001c0  02 00 83 fe 3f 86 01 00  00 00 c6 17 21 00 00 00  |....?.......!...|
+000001d0  01 87 8e fe ff ff c7 17  21 00 4d d3 de 00 00 00  |........!.M.....|
+000001e0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 00 00  |................|
+000001f0  00 00 00 00 00 00 00 00  00 00 00 00 00 00 55 aa  |..............U.|
 ```