Welcome to Caterpillar's documentation!
=======================================

*caterpillar* is a powerful python framework designed to navigate through structured
binary data. This framework operates as a declarative parser and builder using standard
Python class definitions and annotations.

Whetting Your Appetite
----------------------

If you're involved in reverse engineering or working with custom or proprietary file
formats, there often comes a need to structure data in a way that is both easy and
efficient.

🐛 lets you define standard structs with a fixed size while also supporting dynamic
structs that adjust their size based on the current context. This framework enables you
to write complex structures in a compact and readable manner.

.. code-block::
   :caption: Simple example of a custom struct

   @struct
   class Format:
      magic: b"Foo"                       # constant values
      name: CString(...)                  # C-String without a fixed length
      value: le + uint16                  # little endian encoding
      entries: be + CString[uint32::]     # arrays with big-endian prefixed length

.. admonition:: Hold up, wait a minute!

   How does this even work? Is this still Python? Answers to these questions are given
   in the general :ref:`introduction`.

Working with defined classes is as straightforward as working with normal classes. *All
constant values are created automatically!*

>>> obj = Format(name="Hello, World!", value=10, entries=["Bar", "Baz"])
>>> print(obj)
Format(magic=b'Foo', name='Hello, World!', value=10, entries=['Bar', 'Baz'])

Packing and unpacking have never been easier:

>>> pack(obj)
b'FooHello, World!\x00\n\x00\x00\x00\x00\x02Bar\x00Baz\x00'
>>> unpack(Format, _)
Format(magic=b'Foo', name='Hello, World!', value=10, entries=['Bar', 'Baz'])

- What about documentation?

   There are specialized options created only for documentation purposes, so you don't
   have to worry about documenting fields. Just apply the documentation as usual.

- You want to optimize memory space?

   No problem! It is possible to shrink the memory space occupied by unpacked objects up
   to 4 times. More information are provided when discussing available configuration
   :ref:`options`.

Where to start?
---------------

It is recommended to take a look at the explanation of the internal :ref:`datamodel` to get
in touch with all forms of structs. Additionally, there's a detailed documentation on
what configuration options can be used. Alternatively you can follow the :ref:`tutorial-index`.

.. grid:: 1 2 3 4

   .. grid-item-card:: Tutorial
      :link: tutorial/index.html

      User-friendly tutorial to *caterpillar*.

   .. grid-item-card:: Reference
      :link: reference/index.html

      Information about the internal data model of *caterpillar*.

   .. grid-item-card:: Library
      :link: library/index.html

      Source code documentation generated by Sphinx.

   .. grid-item-card:: Development
      :link: development/index.html

      Changelog and contributing information.

.. toctree::
   :maxdepth: 3
   :hidden:
   :caption: Contents:

   installing/index.rst
   tutorial/index.rst
   reference/index.rst
   library/index.rst
   development/index.rst

.. seealso::
   * `Github Source <https://github.com/MatrixEditor/caterpillar>`_
   * `Github Issues <https://github.com/MatrixEditor/caterpillar/issues>`_
   * `Discussions <https://github.com/MatrixEditor/caterpillar/discussions>`_

Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`