Caterpillar

https://matrixeditor.github.io/caterpillar/
Admin
Caterpillar is a powerful Python framework for parsing and building structured binary data using...
Tokens:208,715
Snippets:1,481
Trust Score:8.3
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install Caterpillar with Packaging Extras

Source: https://matrixeditor.github.io/caterpillar/_sources/installing/index.rst

Installs the Caterpillar library from its GitHub repository with specific packaging extras enabled, such as LZO compression, encryption, or all optional dependencies. Replace $NAME with the desired extra (e.g., lzo, crypt, all).

```bash
pip install "caterpillar[$NAME]@git+https://github.com/MatrixEditor/caterpillar.git"
```

--------------------------------

### Install caterpillar with packaging extras using PIP

Source: https://matrixeditor.github.io/caterpillar/installing/index

Installs the caterpillar library with specific optional dependencies enabled using pip. Replace '$NAME' with 'lzo', 'crypt', or 'all' to install corresponding extras.

```bash
pip install "caterpillar[$NAME]@git+https://github.com/MatrixEditor/caterpillar.git"

```

--------------------------------

### Install Caterpillar with Native C Extension from Git

Source: https://matrixeditor.github.io/caterpillar/_sources/installing/index.rst

Installs the Caterpillar library from its GitHub repository, including the native C extension. This requires specifying the subdirectory within the Git URL and may involve setting environment variables like CP_ENABLE_NATIVE.

```bash
pip install git+https://github.com/MatrixEditor/caterpillar/#subdirectory=src/ccaterpillar
```

--------------------------------

### Install Caterpillar from Git Repository

Source: https://matrixeditor.github.io/caterpillar/_sources/installing/index.rst

Installs the Caterpillar library directly from its GitHub repository using pip. This method is useful if you need the latest development version or if the Python package is not up-to-date. Ensure you add '-e' if cloning the repository for developer mode.

```bash
pip install git+https://github.com/MatrixEditor/caterpillar.git
```

--------------------------------

### Install caterpillar from Git using PIP

Source: https://matrixeditor.github.io/caterpillar/installing/index

Installs the caterpillar library directly from its GitHub repository using pip. This method is useful when the latest version or specific branches are needed. It does not include native C extensions by default.

```bash
pip install git+https://github.com/MatrixEditor/caterpillar.git

```

--------------------------------

### Installing the C Extension

Source: https://matrixeditor.github.io/caterpillar/_sources/reference/capi/extension.rst

Demonstrates the command used to install the compiled C extension module. This command is executed from the root of the extension project directory.

```bash
pip install -v .
```

--------------------------------

### ContextPath Initialization Examples

Source: https://matrixeditor.github.io/caterpillar/_modules/caterpillar/context

Demonstrates the initialization of ContextPath objects with different path configurations. Includes examples for initializing with a specific object, an empty context, a parent-child relationship, and the root path.

```python
this = ContextPath(CTX_OBJECT)
ctx = ContextPath()
parent = ContextPath(".".join([CTX_PARENT, CTX_OBJECT]))
root = ContextPath(CTX_ROOT)
```

--------------------------------

### Install caterpillar-py using PIP

Source: https://matrixeditor.github.io/caterpillar/installing/index

Installs the Python-only version of the caterpillar library using pip. This is the simplest way to get started if C extensions are not required.

```bash
pip install caterpillar-py

```

--------------------------------

### Install Caterpillar Python Package

Source: https://matrixeditor.github.io/caterpillar/_sources/installing/index.rst

Installs the Python-only version of the Caterpillar library using pip. This is the simplest installation method and has no fixed dependencies, allowing it to run out of the box.

```console
pip install caterpillar-py
```

--------------------------------

### Install specific subdirectory from Git using PIP

Source: https://matrixeditor.github.io/caterpillar/installing/index

Installs the caterpillar library by specifying a subdirectory within the Git repository. This command is used to install the 'ccaterpillar' component directly.

```bash
pip install git+https://github.com/MatrixEditor/caterpillar/#subdirectory=src/ccaterpillar

```

--------------------------------

### Practical Bitfield Example for PNG Chunk Options (Python)

Source: https://matrixeditor.github.io/caterpillar/tutorial/advanced/bitfield

Provides a practical example of using bitfields to define options for PNG file chunks. It demonstrates how to structure flags like `ancillary`, `private`, `reserved`, and `safe_to_copy` using a nested bitfield definition (`ChunkOption`) within a struct (`ChunkOptions`).

```python
@bitfield(opions={S_DISCARD_UNNAMED})
class ChunkOption:
    _     : 2               # <-- first two bits are not used
    value : 1               # automatically boolean

@struct
class ChunkOptions:
    ancillary    : ChunkOption # f0
    private      : ChunkOption # f1
    reserved     : ChunkOption # f2
    safe_to_copy : ChunkOption # f3

```

--------------------------------

### Setup Type Object for Module (C)

Source: https://matrixeditor.github.io/caterpillar/_sources/reference/capi/module.rst

Initializes the type object for a given module using the CpModule_SetupType macro. It checks for errors during PyType_Ready initialization, returning NULL if it fails. This is crucial for module setup in Python C extensions.

```c
if (PyType_Ready(op) < 0)
    return NULL;
```

--------------------------------

### Bitfield Definition Example

Source: https://matrixeditor.github.io/caterpillar/reference/datamodel/bitfield

Demonstrates a basic Bitfield definition with named fields and their corresponding bit sizes. This example shows how different data types like 'char' and 'uint32' are incorporated into the bitfield.

```python
@bitfield
class Format:
    a1: 2
    a2: 1
    _ : 0
    b1: char
    c1: uint32

```

--------------------------------

### Setup Module Type Object (C)

Source: https://matrixeditor.github.io/caterpillar/reference/capi/module

Sets up the type object for a given module object using CpModule_SetupType. This is a macro that expands to a check for PyType_Ready, returning NULL on failure.

```c
#define CpModule_SetupType(op)\
    if (PyType_Ready(op) < 0)\
        return NULL;
```

--------------------------------

### Bitfield Layout Example

Source: https://matrixeditor.github.io/caterpillar/reference/datamodel/bitfield

Illustrates the resulting byte layout for a given Bitfield definition. It shows how bitfield groups are aligned and the number of bits allocated to each group.

```text
Group      Pos       Bits
a          0x00      8
b          0x01      8
c          0x02      32

```

--------------------------------

### Basic Python Action Example

Source: https://matrixeditor.github.io/caterpillar/_sources/tutorial/advanced/actions.rst

Demonstrates a simple pack action in Python using a lambda function to print a message during struct packing. This showcases side effects like logging or validation.

```python
from caterpillar import struct, Action, uint8

@struct
class Format:
    _: Action(pack=lambda ctx: print("Hello, World!"))
    a: uint8
```

--------------------------------

### Compare Binary Structure Definition with Construct

Source: https://matrixeditor.github.io/caterpillar/_sources/reference/introduction.rst

Provides a Python code snippet for defining a binary structure using the Construct library, used for comparison with Caterpillar. This code aims to achieve similar functionality to the Caterpillar example.

```python
# Code for construct library comparison would be here, based on the provided literalinclude directive.
```

--------------------------------

### Use Greedy Parsing with CString in Python

Source: https://matrixeditor.github.io/caterpillar/reference/datamodel/processing_classes

Shows an example of using greedy parsing with a CString constructor. The Ellipsis ('...') indicates that the CString should consume all available bytes until a null terminator is encountered.

```python
field = Field(CString(...))
unpack(field, b"abcd\x00")

```

--------------------------------

### Install Start Action for Digest in Struct Definition (Python)

Source: https://matrixeditor.github.io/caterpillar/_modules/caterpillar/fields/digest

Installs the 'start' action for a digest field during struct definition. This is typically used within a 'with' block to initiate checksum calculation. It prevents duplicate start actions and ensures unique digest names. Returns the current Digest instance.

```python
def __enter__(self) -> Self:
        """
        Install the start action for the digest field during struct definition.

        This method is used in a `with` block to set up the digest calculation at the beginning.

        :return: The current Digest instance for further use.
        :rtype: Self
        :raises ValueError: If the start action already exists.
        """
        frame = sys._getframe(1)
        annotations = self._get_annotations(frame)
        # 1. install action to create checksum
        start_action_name = f"{self.name}_start"
        if start_action_name in annotations:
            raise ValueError(
                (
                    f"Digest with start action {self.name!r} already exists! "
                    "Make sure that each digest uses a unique name."
                )
            )

        if self.name in annotations:
            raise ValueError(
                (
                    f"Digest with name {self.name!r} already exists "
                    "before the start action. Make sure that each digest "
                    "uses a unique name."
                )
            )

        annotations[start_action_name] = Action(self.begin, self.begin)
        return self
```

--------------------------------

### C Extension Module Initialization

Source: https://matrixeditor.github.io/caterpillar/_sources/reference/capi/extension.rst

Shows the essential C code for initializing a Caterpillar extension module. It includes the necessary header file and the PyInit function, which imports the Caterpillar API and sets up the module.

```c
#include "caterpillar/caterpillar.h"

PyMODINIT_FUNC
PyInit__example(void) {
    PyObject *m;

    import_caterpillar(); // import and setup API

    /* create and setup module */
    // ...
    return m;
}
```

--------------------------------

### Get Context Value by Path (Caterpillar)

Source: https://matrixeditor.github.io/caterpillar/reference/datamodel/protocols/contextlike

Retrieves a value from the context using a specified path. The implementation determines if nested paths are supported, with dot notation as the default separator. For example, 'foo.bar' resolves 'foo' then its 'bar' attribute.

```Python
object.__context_getattr__(_self_ , _path_)
```

```Python
def __context_getattr__(self, path: str):
    # Implementation details...
    pass
```

--------------------------------

### Get Field Name

Source: https://matrixeditor.github.io/caterpillar/_modules/caterpillar/fields/_base

Retrieves the name of the field. It attempts to get the name using `getattr` with a default of `None` if the name attribute is not found.

```python
def get_name(self):
        return getattr(self, "__name__", None)
```

--------------------------------

### Get Flags from an Object in Python

Source: https://matrixeditor.github.io/caterpillar/_modules/caterpillar/options

The `get_flags` function retrieves the flags associated with an object. It attempts to get the 'flags' attribute by default, but an alternative attribute name can be specified.

```python
def get_flags(obj, attr=None):
    """
    Get the flags associated with an object.

    :param obj: The object.
    :param attr: The attribute name containing the flags (default is "flags").
    :return: The set of flags, or None if no flags are present.
    """
    return getattr(obj, attr or "flags", None)

```

--------------------------------

### CMake Configuration for C Extension

Source: https://matrixeditor.github.io/caterpillar/_sources/reference/capi/extension.rst

Provides an example CMakeLists.txt file for configuring the build system of a C extension module. It demonstrates how to find the Python development components, determine Caterpillar include directories, and define the C extension library using scikit-build.

```cmake
cmake_minimum_required(VERSION 3.15...3.26)
project(${SKBUILD_PROJECT_NAME} LANGUAGES C)

# Setup Python Development Module
find_package(
    Python
    COMPONENTS Interpreter Development.Module
    REQUIRED)

# Either setup the include directory manually or use caterpillar directly
set(CP_INCLUDE_DIR "...")
# or
execute_process(
    COMMAND "${Python_Executable}" -m caterpillar --include-dir
    OUTPUT_STRIP_TRAILING_WHITESPACE OUTPUT_VARIABLE CP_INCLUDE_DIR
)

# Setup the C extension module
python_add_library(
    _example       # module name
    MODULE

    src/_example.c # source files

    WITH_SOABI
)

# setup include directories
target_include_directories(
    _example
    PRIVATE
    ${CP_INCLUDE_DIR}
)

# install extension
install(
    TARGETS _example
    DESTINATION example # use '.' to install directly without parent package
)
```

--------------------------------

### Utility to Get Instantiated Object

Source: https://matrixeditor.github.io/caterpillar/_modules/caterpillar/fields/crypto

A helper method to get an instance of a specified type. It handles cases where the provided field is already an instance or needs to be instantiated using provided arguments and context.

```python
def get_instance(self, type_, field, args, context):
    """
    Get an instance of a specified type.

    :param type_: The desired type of the instance.
    :type type_: type
    :param field: The field or instance.
    :type field: Any
    :param args: Additional arguments for the instance.
    :type args: Any
    :param context: The current operation context.
    :type context: _ContextLambda
    :return: An instance of the specified type.
    :rtype: Any
    """
    if isinstance(field, type_) or not field:
        return field

    if isinstance(args, dict):
        args, kwargs = (), get_kwargs(args, context)
    else:
        args, kwargs = get_args(args, context), {}
    return field(*args, **kwargs)

```

--------------------------------

### CpModule_SetupType Macro

Source: https://matrixeditor.github.io/caterpillar/_sources/reference/capi/module.rst

Macro for setting up the type object for a module.

```APIDOC
## CpModule_SetupType Macro

### Description
Sets up the type object for the given module object. This is a C macro used internally for module initialization.

### Method
N/A (C macro)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```c
CpModule_SetupType(op);
```

### Response
#### Success Response (N/A)
- **void** - The macro performs an operation and returns void. It might return NULL if `PyType_Ready` fails.

#### Response Example
N/A
```

--------------------------------

### Finalize Current Bit-field Group and Start New One

Source: https://matrixeditor.github.io/caterpillar/_sources/library/options.rst

The B_GROUP_NEW option finalizes the current bit-field group by aligning it, then starts a new group and adds the annotated field to it. This allows for creating distinct aligned sections within a bit-field structure.

```python
import caterpillar.options

caterpillar.options.B_GROUP_NEW
```

```python
@bitfield
class Format:
    a1: 4
    a2: 4
    # Finalize current group and start new one with 8-bit alignment:
    b1: (1, B_GROUP_NEW)
```

--------------------------------

### Implement Bitfields in Python

Source: https://matrixeditor.github.io/caterpillar/tutorial/index

Illustrates the core concepts and syntax for defining and using bitfields within the Caterpillar framework. This allows for fine-grained control over individual bits within a byte or word, essential for packed binary data.

```Python
from caterpillar import Struct, Bitfield, U8

class ExampleBitfield(Struct):
    class Flags(Bitfield):
        flag1: U8(1)
        flag2: U8(1)
        value: U8(6)

    status: Flags

# Example usage:
# bf = ExampleBitfield()
# bf.status.flag1 = 1
# bf.status.value = 42
# print(bf.status.pack())
```

--------------------------------

### Action-like Object Methods

Source: https://matrixeditor.github.io/caterpillar/_sources/reference/datamodel/protocols/actionlike.rst

Details on the __action_pack__ and __action_unpack__ methods for action-like objects.

```APIDOC
## Action-like Objects

### Description
Action-like objects provide a flexible mechanism for performing custom operations during data processing. They are defined to modify or interact with data at various stages of serialization or deserialization.

### Methods

#### `object.__action_pack__(self, context)`

- **Description**: Invoked when data is serialized. This method can be used for tasks such as calculating checksums or logging.
- **Method**: Method call within a Python object.
- **Parameters**:
  - `context` (_ContextLike) - The serialization context.

#### `object.__action_unpack__(self, context)`

- **Description**: Invoked when data is deserialized. This method is typically used for validation, verification, or any other operation that should run during the unpacking process.
- **Method**: Method call within a Python object.
- **Parameters**:
  - `context` (_ContextLike) - The deserialization context.

### Notes
- To implement an action-like object, only one of these methods needs to be defined; defining both is optional.

### Derived Protocols

#### `_ActionLike`

- **Description**: Represents an object that supports both `__action_pack__` and `__action_unpack__`.
- **Methods**:
  - `__action_pack__(self, context: _ContextLike) -> None`
  - `__action_unpack__(self, context: _ContextLike) -> None`

#### `_SupportsActionUnpack`

- **Description**: Represents an object that supports the `__action_unpack__` method.
- **Methods**:
  - `__action_unpack__(self, context: _ContextLike) -> None`

#### `_SupportsActionPack`

- **Description**: Represents an object that supports the `__action_pack__` method.
- **Methods**:
  - `__action_pack__(self, context: _ContextLike) -> None`
```

--------------------------------

### Create LZO Compression Struct with Python

Source: https://matrixeditor.github.io/caterpillar/_modules/caterpillar/fields/compression

This Python function, 'create_lzo_compression_struct', generates a structure for LZO compression. It requires the 'lzallright' library to be installed via 'pip install lzallright'. The function takes compression and decompression keyword arguments and returns a compressed object or raises a NotImplementedError if the library is unavailable.

```python
import lzallright

def create_lzo_compression_struct(obj, comp_kwargs=None,
    decomp_kwargs=None,
):
    """
    Create a struct representing LZO compression.
    """
    try:
        # install package manuall with pip install lzallright
        import lzallright

        return compressed(lzallright.LZOCompressor(), obj, comp_kwargs, decomp_kwargs)
    except ImportError:
        raise NotImplementedError("Could not import lzallright!")
```

--------------------------------

### Get Tail of Chain

Source: https://matrixeditor.github.io/caterpillar/library/fields/field_model

Retrieves the tail (last structure) of the chain. Returns the tail structure.

```python
def tail# → StructLike:
    """
    Get the tail of the chain, i.e., the last structure. 

    Returns:
        
      The tail of the chain.
    Return type:
        
      _StructLike 
    """
    pass
```

--------------------------------

### Get Head of Chain

Source: https://matrixeditor.github.io/caterpillar/library/fields/field_model

Retrieves the head (first structure) of the chain. Returns the head structure.

```python
def head()# → StructLike:
    """
    Get the head of the chain, i.e., the first structure. 

    Returns:
        
      The head of the chain.
    Return type:
        
      _StructLike 
    """
    pass
```

--------------------------------

### Define a Sequence with Fields

Source: https://matrixeditor.github.io/caterpillar/reference/datamodel/sequence

Demonstrates the basic instantiation of a Sequence object by providing a dictionary of fields and their types. This is the default way to create a sequence with all default options.

```python
>>> Format = Sequence({"a": uint8, "b": uint32})

```

--------------------------------

### Caterpillar Library - Section O

Source: https://matrixeditor.github.io/caterpillar/genindex

Documentation for components starting with 'O' in the Caterpillar library, covering options, contexts, and exceptions.

```APIDOC
## Caterpillar Library - Section O

### Description
This section covers components in the Caterpillar library starting with 'O', including options attributes, context factory options, and exception classes.

### Attributes

*   **O_ARRAY_FACTORY** (caterpillar.options attribute): Option related to array factories.
*   **O_CONTEXT_FACTORY** (caterpillar.context attribute): Option related to context factories.
*   **offset** (caterpillar.fields.Field property): Property representing the offset of a field.
*   **options** (caterpillar.fields.Field property): Property to access options of a field.

### Classes

*   **object.NIBHeader** (class in examples.formats.nibarchive): Represents the NIB header object.
*   **OptionError** (class in caterpillar.exception): Exception class for option-related errors.
```

--------------------------------

### Unpack Data with Pointer on x86 Architecture

Source: https://matrixeditor.github.io/caterpillar/_sources/tutorial/advanced/pointers.rst

Shows how to unpack binary data into a Caterpillar struct with a pointer field on an x86 architecture. It illustrates the resulting object representation and how to access the referenced object.

```python
>>> data = b"\x00\x00\x00\x04Hello, World!\x00"
>>> o = unpack(Format, data, _arch=x86)
Format(name=<str* 0x4>)
>>> o.name.obj
'Hello, World!'
```

--------------------------------

### Caterpillar Library - Section F

Source: https://matrixeditor.github.io/caterpillar/genindex

Documentation for classes, attributes, and methods starting with 'F' in the Caterpillar library.

```APIDOC
## Caterpillar Library - Section F

### Description
This section details various components in the Caterpillar library whose names start with 'F'. It includes options attributes, classes, and methods related to fields and their operations.

### Classes and Attributes

*   **F_DYNAMIC** (caterpillar.options attribute)
*   **F_KEEP_POSITION** (caterpillar.options attribute)
*   **F_OFFSET_OVERRIDE** (caterpillar.options attribute)
*   **F_SEQUENTIAL** (caterpillar.options attribute)
*   **Field** (class in caterpillar.fields)
*   **FieldMixin** (class in caterpillar.fields)
*   **FieldStruct** (class in caterpillar.fields)
*   **Flag** (class in caterpillar.options)
*   **float16** (caterpillar.fields attribute)
*   **float32** (caterpillar.fields attribute)
*   **float64** (caterpillar.fields attribute)

### Methods

*   **field.__ior__()**: Built-in function for in-place bitwise OR operation on fields.
*   **field.__ixor__()**: Built-in function for in-place bitwise XOR operation on fields.
*   **field.__or__()**: Built-in function for bitwise OR operation on fields.
*   **field.__xor__()**: Built-in function for bitwise XOR operation on fields.
*   **flag()** (caterpillar.model.SetAlignment static method): Static method to set alignment flags.
*   **flags** (caterpillar.fields.Field property): Property to access flags associated with a field.
*   **from_int()**: Factory method available for `BitfieldValue`, `Char`, and `Enum` types.
    *   (caterpillar.model.BitfieldValueFactory method)
    *   (caterpillar.model.CharFactory method)
    *   (caterpillar.model.EnumFactory method)

### Attributes

*   **field_kwds** (caterpillar.model.TemplateTypeVar attribute): Attribute for keyword arguments in template type variables.
```

--------------------------------

### Importing Caterpillar Components

Source: https://matrixeditor.github.io/caterpillar/_sources/tutorial/first_steps/index.rst

This snippet shows the necessary imports from the 'caterpillar.py' library to work with data structures, unsigned integers, byte sequences, and field definitions. These imports are assumed to be present before running subsequent code examples.

```python
from caterpillar.py import struct, uint32, uint8, Bytes, F, Field
```

--------------------------------

### Install End Action for Digest in Struct Definition (Python)

Source: https://matrixeditor.github.io/caterpillar/_modules/caterpillar/fields/digest

Installs the 'end' action for a digest field and finalizes struct field definitions within a 'with' block. This method completes the digest calculation and assigns the field. It raises a ValueError if the end action already exists. It also handles verification actions.

```python
def __exit__(self, *_) -> None:
        """
        Install the end action for the digest field and finalize the struct field definitions.

        This method is used to finalize the digest field in a `with` block.

        :raises ValueError: If the end action already exists.
        """
        frame = sys._getframe(1)
        annotations = self._get_annotations(frame)
        # 2. add action to finish checksum
        end_action_name = f"{self.name}_end"
        if end_action_name in annotations:
            raise ValueError(
                (
                    f"Digest with end action {self.name!r} already exists! "
                    "Make sure that each checksum uses a unique name."
                )
            )
        annotations[end_action_name] = Action(self.end_pack, self.end_unpack)
        annotations[self.name] = Field(self.struct)
        frame.f_locals[self.name] = _DigestValue()
        if self._verify:
            annotations[f"{self.name}_verify"] = Action(unpack=self.verfiy)
```

--------------------------------

### Get Chain Tail Type

Source: https://matrixeditor.github.io/caterpillar/library/fields/field_model

Retrieves the type of the tail structure within the chain. Returns a type object.

```python
def __type__() → type:
    """
    Get the type of the tail structure in the chain. 

    Returns:
        
      The type of the tail structure.
    Return type:
        
      type 
    """
    pass
```

--------------------------------

### Advanced Bitfield Definition with Extended Syntax

Source: https://matrixeditor.github.io/caterpillar/reference/datamodel/bitfield

Showcases the extended syntax for Bitfield definitions, including inline comments explaining each part. This example utilizes various syntax rules for defining fields with different types, alignments, and factories.

```python
@bitfield
class Format: #                                               -.
    # Any annotation that can be converted by a TypeConverter  | 1. Group
    # into as _StructLike object is allowed.                   | (3 Bytes)
    magic: b"foo" # bytes                                     -'

    # Syntax according to (1) and (2)                         -.
    version : 4 # int                                          | 2. Group
    state   : 3 # int                                          | (1 Byte / 8 Bits)
    _       : 0 # ignored/removed                             -'

    # Extended Syntax (5)
    flag1 : (1, SetAlignment(16))     # bool, new alignment   -.
    flag2 : 1                         # bool                   | 3. Group
    name  : (12, CharFactory)         # str                    | (2 Bytes / 16 Bits)
    type  : (2, SimpleEnum, EndGroup) # SimpleEnum            -'

```

--------------------------------

### Caterpillar Library - Section I

Source: https://matrixeditor.github.io/caterpillar/genindex

Documentation for classes and methods starting with 'I' in the Caterpillar library, covering field types, exceptions, and state checks.

```APIDOC
## Caterpillar Library - Section I

### Description
This section provides documentation for components in the Caterpillar library starting with 'I', including field classes, exceptions, and methods for checking various states and properties.

### Classes

*   **If** (class in caterpillar.fields)
*   **Int** (class in caterpillar.fields)
*   **InvalidValueError** (class in caterpillar.exception)

### Attributes

*   **int16** (caterpillar.fields attribute)
*   **int32** (caterpillar.fields attribute)
*   **int64** (caterpillar.fields attribute)
*   **int8** (caterpillar.fields attribute)

### Methods

*   **is_action()** (caterpillar.model.BitfieldEntry method): Checks if a bitfield entry represents an action.
*   **is_empty()** (caterpillar.model.BitfieldGroup method): Checks if a bitfield group is empty.
*   **is_enabled()** (caterpillar.fields.Field method): Checks if a field is enabled.
*   **is_field()** (caterpillar.model.BitfieldGroup method): Checks if a bitfield group contains a field.
*   **is_padding()** (caterpillar.fields.PyStructFormattedField method): Checks if a formatted field is padding.
*   **is_seq()** (caterpillar.fields.Field method): Checks if a field is a sequence.
*   **issigned()** (in module caterpillar.model): Checks if a model component is signed.
*   **istemplate()** (in module caterpillar.model): Checks if a model component is a template.
```

--------------------------------

### Set Custom Context Factory in Caterpillar

Source: https://matrixeditor.github.io/caterpillar/_sources/tutorial/basics/context.rst

Shows how to replace the default context factory with a custom one, specifically the C-extension implementation for potentially faster packing and unpacking. This involves importing and assigning the desired context class to the O_CONTEXT_FACTORY.

```python
from caterpillar.context import O_CONTEXT_FACTORY
from caterpillar.c import c_Context
O_CONTEXT_FACTORY.value = c_Context
```

--------------------------------

### CpContext_New

Source: https://matrixeditor.github.io/caterpillar/reference/capi/objects/contextobj

Creates a new context object and returns it. Returns NULL if an error occurs.

```APIDOC
## CpContext_New

### Description
Creates a new context and returns it. Returns _NULL_ if an error occurs.

### Method
`CpContext_New`

### Return Value
New reference to the created context object, or NULL if an error occurs.
```

--------------------------------

### Get Atom Type - C API

Source: https://matrixeditor.github.io/caterpillar/_sources/reference/capi/parsing.rst

Returns the type of the given atom object.

```c
PyObject *CpAtom_TypeOf(PyObject *value);
```

--------------------------------

### Chain Structs with ZLibCompressed and Format

Source: https://matrixeditor.github.io/caterpillar/tutorial/advanced/chaining

Demonstrates how to chain struct operations for sequential data processing. In this example, ZLibCompressed is used for decompression, followed by Format for further data processing. This approach allows for flexible data pipelines but may introduce complexity and performance considerations.

```python
chain = ZLibCompressed(...) & Format
```

--------------------------------

### Caterpillar Library - Section M

Source: https://matrixeditor.github.io/caterpillar/genindex

Documentation for components starting with 'M' in the Caterpillar library, including field types, byte orders, and module information.

```APIDOC
## Caterpillar Library - Section M

### Description
This section covers components in the Caterpillar library starting with 'M', including field types, byte order specifications, and module information.

### Classes

*   **Memory** (class in caterpillar.fields)
*   **NIBHeader** (class in formats.nibarchive.object) - This seems to be a duplicate entry, likely intended for section N.

### Attributes

*   **magic**:
    *   (examples.formats.nibarchive.object.NIBHeader.NIBHeader attribute)
    *   (formats.nibarchive.NIBHeader attribute)
*   **max_size** (caterpillar.model.UnionHook attribute)
*   **MIPS** (caterpillar.byteorder attribute): Represents the MIPS byte order.
*   **MIPS64** (caterpillar.byteorder attribute): Represents the MIPS64 byte order.
*   **MODE_PACK** (in module caterpillar.shared): Packing mode constant.
*   **MODE_UNPACK** (in module caterpillar.shared): Unpacking mode constant.

### Methods

*   **matches()** (caterpillar.registry.TypeConverter method): Checks if a type converter matches a given type.
*   **mode()** (caterpillar.fields.Encrypted method): Retrieves the mode of an encrypted field.

### Modules

*   **caterpillar.registry**
*   **caterpillar.shared**
```

--------------------------------

### Caterpillar Library - Section H

Source: https://matrixeditor.github.io/caterpillar/genindex

Documentation for methods and properties starting with 'H' in the Caterpillar library, related to checking conditions, flags, and sequence properties.

```APIDOC
## Caterpillar Library - Section H

### Description
This section details components in the Caterpillar library starting with 'H', primarily focusing on methods for checking conditions and flags, as well as properties related to sequence heads.

### Methods

*   **has_condition()** (caterpillar.fields.Field method): Checks if a field has a condition.
*   **has_flag()** (caterpillar.fields.Field method): Checks if a field has a specific flag.
    *   (in module caterpillar.options)
*   **has_option()** (caterpillar.model.Sequence method): Checks if a sequence has a specific option.
*   **hasstruct()** (in module caterpillar.shared): Checks if a shared component has struct information.

### Properties

*   **head** (caterpillar.fields.Chain property): Property representing the head of a chain.
```

--------------------------------

### CpModule_SetupType

Source: https://matrixeditor.github.io/caterpillar/reference/capi/module

Function to set up the type object for a given module object.

```APIDOC
## CpModule_SetupType

### Description
Sets up the type object for the given module object. Expands to:
```c
if (PyType_Ready(op) < 0)
    return NULL;
```

### Method
Function Call

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
None

### Response
#### Success Response (0)
Indicates successful setup.

#### Error Response (-1)
Indicates failure during type setup.

#### Response Example
`0` on success, `NULL` on failure.
```

--------------------------------

### Context Lambda Implementation

Source: https://matrixeditor.github.io/caterpillar/_sources/reference/datamodel/protocols/contextlambda.rst

This section details how to implement a Context Lambda by defining the __call__ method.

```APIDOC
## Context Lambda Implementation

### Description
To implement a *context lambda*, a class must define the :meth:`__call__` method. The library treats general callable objects and *context lambdas* identically.

### Method
`__call__`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
# Example of a class implementing a context lambda
class MyContextLambda:
    def __call__(self, context):
        # Return the desired result based on the context
        return context.some_value * 2
```

### Response
#### Success Response (200)
- **__call__** (_RT) - The method that is called when the lambda is invoked.

#### Response Example
```json
{
  "result": "The result returned by the context lambda"
}
```
```

--------------------------------

### Caterpillar Library - Section G

Source: https://matrixeditor.github.io/caterpillar/genindex

Documentation for classes, methods, and attributes starting with 'G' in the Caterpillar library, focusing on data retrieval and module state.

```APIDOC
## Caterpillar Library - Section G

### Description
This section covers components in the Caterpillar library starting with 'G', including methods for retrieving data from bitfield groups, fields, and accessing module states.

### Methods

*   **get_bits()** (caterpillar.model.BitfieldGroup method): Retrieves bits from a bitfield group.
*   **get_field()** (caterpillar.model.BitfieldGroup method): Retrieves a specific field from a bitfield group.
*   **get_flag()** (in module caterpillar.options): Retrieves a flag from the options module.
*   **get_flags()** (in module caterpillar.options): Retrieves all flags from the options module.
*   **get_instance()** (caterpillar.fields.Encrypted method): Retrieves an instance of an encrypted field.
*   **get_name()** (caterpillar.fields.Field method): Retrieves the name of a field.
*   **get_offset()** (caterpillar.fields.Field method): Retrieves the offset of a field.
*   **get_size()** (caterpillar.model.BitfieldGroup method): Retrieves the size of a bitfield group.
*   **get_struct()** (caterpillar.fields.Field method): Retrieves the struct representation of a field.
*   **get_type()** (caterpillar.fields.Field method): Retrieves the type of a field.
*   **getbits()** (in module caterpillar.model): Retrieves bits from a model component.
*   **getch()** (caterpillar.byteorder.DynByteOrder method): Retrieves a character with dynamic byte order.
*   **getstruct()** (in module caterpillar.shared): Retrieves struct information from shared components.

### C Functions

*   **get_global_module_state**: C function to get the global module state.
*   **get_module_state**: C function to get the module state.

### Classes

*   **NewGroup** (in module caterpillar.model)

### Byte Orders

*   **LittleEndian** (caterpillar.byteorder attribute)

### Compressed Formats

*   **LZMACompressed()** (in module caterpillar.fields)
*   **LZOCompressed()** (in module caterpillar.fields)
```

--------------------------------

### Compare Binary Structure Definition with MRCrowbar

Source: https://matrixeditor.github.io/caterpillar/_sources/reference/introduction.rst

Includes a Python code snippet defining a binary structure with MRCrowbar, facilitating a comparative analysis against Caterpillar. This snippet is sourced from an external file.

```python
# Code for mrcrowbar library comparison would be here, based on the provided literalinclude directive.
```

--------------------------------

### Caterpillar Library - Section L

Source: https://matrixeditor.github.io/caterpillar/genindex

Documentation for classes, attributes, and methods starting with 'L' in the Caterpillar library, including field types and byte order specifications.

```APIDOC
## Caterpillar Library - Section L

### Description
This section details components in the Caterpillar library starting with 'L'. It includes classes for fields, methods for calculating length, and byte order attributes.

### Classes

*   **Lazy** (class in caterpillar.fields)

### Methods

*   **length()** (caterpillar.fields.Field method): Calculates the length of a field.

### Attributes

*   **LittleEndian** (caterpillar.byteorder attribute): Represents the little-endian byte order.

### Compressed Formats

*   **LZMACompressed()** (in module caterpillar.fields)
*   **LZOCompressed()** (in module caterpillar.fields)
```

--------------------------------

### Create a Sub-Template (Partial Template) in Python

Source: https://matrixeditor.github.io/caterpillar/_sources/tutorial/advanced/templates.rst

Shows how to create a sub-template by deriving from an existing template and deferring some template parameters. This allows for more focused, reusable template components.

```python
# template sub-classes are allowed as well
FormatSubTemplate = derive(FormatTemplate, A=uint8, partial=True) # <- Derived Template
```

--------------------------------

### Get Size of Object - caterpillar.model.sizeof

Source: https://matrixeditor.github.io/caterpillar/library/model/struct

Calculates the size of an object based on its structure. This function is useful for understanding memory usage or determining buffer sizes for serialization.

```APIDOC
## GET /caterpillar.model.sizeof

### Description
Calculates the size of an object based on its structure. This function is useful for understanding memory usage or determining buffer sizes for serialization.

### Method
GET

### Endpoint
caterpillar.model.sizeof

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **obj** (any) - Required - The object whose size needs to be calculated. Must implement the `_SupportsSize` protocol.
- **kwds** (dict) - Optional - Additional keyword arguments.

### Request Example
```python
from caterpillar import model

# Assume my_obj is an object that implements _SupportsSize
# size = model.sizeof(my_obj)
```

### Response
#### Success Response (200)
- **int** - The size of the object in bytes.

#### Response Example
```json
{
  "example": 1024
}
```
```

--------------------------------

### Bytes, Strings, and Prefixed Fields

Source: https://matrixeditor.github.io/caterpillar/_sources/library/fields/common.rst

Documentation for handling raw bytes, strings, and prefixed data structures.

```APIDOC
## Bytes, Strings, and Prefixed Fields

This section covers fields for handling byte sequences and strings, including prefixed structures.

### Supported Fields

- **Memory**: Represents a block of memory. (Removed `encoding` argument in v2.4.0)
- **Bytes**: Field for byte sequences.
- **String**: Field for string data.
- **Prefixed**: Field for data prefixed with a length. (Added support for arbitrary structs in v2.4.0; the second parameter is now a struct instead of an encoding string).
- **CString**: Null-terminated C-style string.
- **ConstString**: Constant string field.
- **ConstBytes**: Constant byte sequence field.
```

--------------------------------

### Get Atom Type (C)

Source: https://matrixeditor.github.io/caterpillar/reference/capi/parsing

Returns the type of a given atom object. This function returns a new reference to the type object.

```c
PyObject *CpAtom_TypeOf(PyObject *value);

```
Tokens:
Raw