examples

Author: andreax79

cstruct/__init__.py

@@ -67,6 +67,9 @@ def define(key: str, value: Any) -> None:
     """
     Define a constant that can be used in the C struct
 
+    Examples:
+        >>> define("INIT_THREAD_SIZE", 16384)
+
     Args:
         key: identifier
         value: value of the constant
@@ -78,8 +81,15 @@ def undef(key: str) -> None:
     """
     Undefine a symbol that was previously defined with define
 
+    Examples:
+        >>> define("INIT_THREAD_SIZE", 16384)
+        >>> undef("INIT_THREAD_SIZE")
+
     Args:
         key: identifier
+
+    Raises:
+        KeyError: If key is not defined
     """
     del DEFINES[key]
 
@@ -88,8 +98,15 @@ def getdef(key: str) -> Any:
     """
     Return the value for a constant
 
+    Examples:
+        >>> define("INIT_THREAD_SIZE", 16384)
+        >>> getdef("INIT_THREAD_SIZE")
+
     Args:
         key: identifier
+
+    Raises:
+        KeyError: If key is not defined
     """
     return DEFINES[key]
 
@@ -98,6 +115,11 @@ def typedef(type_: str, alias: str) -> None:
     """
     Define an alias name for a data type
 
+    Examples:
+        >>> typedef("int", "status")
+        >>> sizeof("status")
+        4
+
     Args:
         type_: data type
         alias: new alias name
@@ -120,6 +142,9 @@ def get_type(type_: str) -> Any:
 
     Returns:
         class: data type class
+
+    Raises:
+        KeyError: If type is not defined
     """
     while type_ in TYPEDEFS:
         type_ = TYPEDEFS[type_]
@@ -148,6 +173,8 @@ def sizeof(type_: str) -> int:
     Examples:
         >>> sizeof("struct Position")
         16
+        >>> sizeof('enum htmlfont')
+        4
         >>> sizeof("int")
         4
 
@@ -156,6 +183,9 @@ def sizeof(type_: str) -> int:
 
     Returns:
         size: size in bytes
+
+    Raises:
+        KeyError: If type is not defined
     """
     while type_ in TYPEDEFS:
         type_ = TYPEDEFS[type_]
@@ -169,7 +199,11 @@ def parse(
     """
     Return a new class mapping a C struct/union/enum definition.
     If the string does not contains any definition, return None.
+    If the string contains multiple struct/union/enum definitions, returns the last definition.
 
+    Examples:
+        >>> cstruct.parse('struct Pair { unsigned char a; unsigned char b; };')
+        <class 'abc.Pair'>
 
     Args:
         __struct__ (str): definition of the struct (or union/enum) in C syntax
@@ -178,11 +212,14 @@ def parse(
 
     Returns:
         cls: __cls__ subclass
+
+    Raises:
+        cstruct.exceptions.ParserError: Parsing exception
+
     """
     if __cls__ is None:
         __cls__ = MemCStruct
     cls_def = parse_struct_def(__struct__, __cls__=__cls__, process_muliple_definition=True, **kargs)
-    print('!!!!!', cls_def, kargs)
     if cls_def is None:
         return None
     return cls_def['__cls__'].parse(cls_def, **kargs)

cstruct/c_parser.py

@@ -51,7 +51,7 @@ def __init__(self, text: str) -> None:
                     _, name, value = line.strip().split(maxsplit=2)
                     DEFINES[name] = c_eval(value)
                 except Exception:
-                    raise ParserError(f"Parsing line {line}")
+                    raise ParserError(f"Parsing line `{line}`")
             else:
                 lines.append(line)
         text = "\n".join(lines)
@@ -124,7 +124,7 @@ def parse_type(tokens: Tokens, __cls__: Type['AbstractCStruct'], byte_order: Opt
         if "[" in next_token:
             t = next_token.split("[")
             if len(t) != 2:
-                raise ParserError("Error parsing: " + next_token)
+                raise ParserError(f"Error parsing: `{next_token}`")
             next_token = t[0].strip()
             vlen_part = t[1]
             vlen_expr = []
@@ -163,7 +163,7 @@ def parse_type(tokens: Tokens, __cls__: Type['AbstractCStruct'], byte_order: Opt
             try:
                 ref = STRUCTS[tail]
             except KeyError:
-                raise ParserError(f"Unknown '{c_type}' '{tail}'")
+                raise ParserError(f"Unknown `{c_type} {tail}`")
     elif c_type.startswith('enum'):
         from .cenum import CEnum
 
@@ -181,7 +181,7 @@ def parse_type(tokens: Tokens, __cls__: Type['AbstractCStruct'], byte_order: Opt
             try:
                 ref = ENUMS[tail]
             except KeyError:
-                raise ParserError(f"Unknown '{c_type}' '{tail}'")
+                raise ParserError(f"Unknown `{c_type} {tail}`")
     else:  # other types
         kind = Kind.NATIVE
         ref = None
@@ -201,7 +201,7 @@ def parse_typedef(tokens: Tokens, __cls__: Type['AbstractCStruct'], byte_order:
         TYPEDEFS[vname] = f"struct {field_type.ref.__name__}"
     t = tokens.pop()
     if t != ';':
-        raise ParserError(f"; expected but {t} found")
+        raise ParserError(f"`;` expected but `{t}` found")
 
 
 def parse_struct_def(
@@ -242,7 +242,7 @@ def parse_struct_def(
             elif name == '{':  # unnamed enum
                 result = parse_enum(tokens, native_format=native_format)
             else:
-                raise ParserError(f"{name} definition expected")
+                raise ParserError(f"`{name}` definition expected")
 
         elif kind in ['struct', 'union']:
             if result:
@@ -257,10 +257,10 @@ def parse_struct_def(
                     tokens, __cls__=__cls__, __is_union__=__is_union__, __byte_order__=__byte_order__, __name__=name
                 )
             else:
-                raise ParserError(f"{name} definition expected")
+                raise ParserError(f"`{name}` definition expected")
 
         else:
-            raise ParserError(f"struct, union, or enum expected - {kind}")
+            raise ParserError(f"struct, union, or enum expected - `{kind}` found")
     return result
 
 
@@ -274,7 +274,7 @@ def parse_enum_def(__def__: Union[str, Tokens], **kargs: Any) -> Optional[Dict[s
         return None
     kind = tokens.pop()
     if kind not in ['enum']:
-        raise ParserError(f"enum expected - {kind}")
+        raise ParserError(f"enum expected - `{kind}` found")
 
     name = tokens.pop()
     native_format = None
@@ -288,7 +288,7 @@ def parse_enum_def(__def__: Union[str, Tokens], **kargs: Any) -> Optional[Dict[s
     elif name == '{':  # unnamed enum
         return parse_enum(tokens)
     else:
-        raise ParserError(f"{name} definition expected")
+        raise ParserError(f"`{name}` definition expected")
 
 
 def parse_enum(
@@ -348,10 +348,10 @@ def parse_enum(
             except (ValueError, TypeError):
                 value = int(int_expr)
         else:
-            raise ParserError(f"{__enum__} is not a valid enum expression")
+            raise ParserError(f"`{__enum__}` is not a valid enum expression")
 
         if name in constants:
-            raise ParserError(f"duplicate enum name {name}")
+            raise ParserError(f"duplicate enum name `{name}`")
         constants[name] = value
 
         if next_token == "}":
@@ -416,15 +416,15 @@ def parse_struct(
         field_type = parse_type(tokens, __cls__, __byte_order__, offset)
         vname = tokens.pop()
         if vname in fields_types:
-            raise ParserError(f"Duplicate member '{vname}'")
+            raise ParserError(f"Duplicate member `{vname}`")
         if vname in dir(__cls__):
-            raise ParserError(f"Invalid reserved member name '{vname}'")
+            raise ParserError(f"Invalid reserved member name `{vname}`")
         # anonymous nested union
         if vname == ';' and field_type.ref is not None and (__is_union__ or field_type.ref.__is_union__):
             # add the anonymous struct fields to the parent
             for nested_field_name, nested_field_type in field_type.ref.__fields_types__.items():
                 if nested_field_name in fields_types:
-                    raise ParserError(f"Duplicate member '{nested_field_name}'")
+                    raise ParserError(f"Duplicate member `{nested_field_name}`")
                 fields_types[nested_field_name] = nested_field_type
             vname = f"__anonymous{anonymous}"
             anonymous += 1
@@ -438,7 +438,7 @@ def parse_struct(
             offset = field_type.offset + field_type.vsize
         t = tokens.pop()
         if t != ';':
-            raise ParserError(f"; expected but {t} found")
+            raise ParserError(f"`;` expected but `{t}` found")
 
     if __is_union__:  # C union
         # Calculate the sizeof union as size of its largest element

cstruct/native_types.py

@@ -66,6 +66,9 @@ def get_native_type(type_: str) -> "AbstractNativeType":
 
     Returns:
         class: data type class
+
+    Raises:
+        KeyError: If type is not defined
     """
     try:
         return NATIVE_TYPES[type_]