Pointer

KonFoo has a Pointer class to reference a memory area in a data source to be mapped with its attached data object.

The Pointer class provides an interface to read the necessary amount of bytes for its attached data object through a byte stream provider from a data source.

The Pointer class provides an interface to write the field values of any container or field in its attached data object through a byte stream provider to the data source.

KonFoo provides the following specialized pointer fields

• a StructurePointer field which refers to a structure.

• a SequencePointer field which refers to a sequence.

• a ArrayPointer field which refers to an array.

• a StreamPointer field which refers to a Stream field.

• a StringPointer field which refers to a String field.

Relative Pointer

KonFoo has a RelativePointer class. The only difference between the a pointer field and a relative pointer field is that the data object is relative addressed by a relative pointer field instead of absolute addressed.

KonFoo provides the following specialized relative pointer fields

• a StructureRelativePointer field which refers to a structure

• a SequenceRelativePointer field which refers to a sequence

• a ArrayRelativePointer field which refers to an array

• a StreamRelativePointer field which refers to a Stream field

• a StringRelativePointer field which refers to a String field

Data Object

A data object of a pointer field can be any field or container class.

Define a Data Object

Define a data object by defining a data object class.

>>> class DataObject(Structure):
...
...     def __init__(self):
...         super().__init__()
...         self.size = Decimal(16)
...         self.item = Pointer()
...         self.index_fields()

>>> # Create an instance of the data object.
>>> data_object = DataObject()

>>> # List the field values of the data object.
>>> data_object.to_list()
[('DataObject.size', 0),
 ('DataObject.item', '0x0')]

>>> # List the field values of the data object as a CSV list.
>>> data_object.to_csv()
[{'id': 'DataObject.size', 'value': 0},
 {'id': 'DataObject.item', 'value': '0x0'}]

>>> # View the data object field values as a JSON string.
>>> data_object.to_json()
'{"size": 0, "item": "0x0"}'

>>> # List the field values of the data object and nested pointers.
>>> data_object.to_list(nested=True)
[('DataObject.size', 0),
 ('DataObject.item', '0x0')]

>>> # List the field values of the data object and nested pointers as a CSV list.
>>> data_object.to_csv(nested=True)
[{'id': 'DataObject.size', 'value': 0},
 {'id': 'DataObject.item', 'value': '0x0'}]

>>> # View the data object and nested pointers field values as a JSON string.
>>> data_object.to_json(nested=True)
'{"size": 0,
  "item": {"value": "0x0",
           "data": null}}'

Define a Data Object Pointer

Define a data object pointer class for the data object attached to the pointer.

>>> class DataObjectPointer(Pointer):
...
...     def __init__(self, address=None, byte_order=BYTEORDER):
...         super().__init__(template=DataObject(),
...                          address=address,
...                          data_order=byte_order)

>>> # Create an instance of the pointer.
>>> pointer = DataObjectPointer()

>>> # List the field values of the pointer.
>>> pointer.to_list()
[('DataObjectPointer.field', '0x0'),
 ('DataObjectPointer.data.size', 0),
 ('DataObjectPointer.data.item', '0x0')]

>>> # List the field values of the pointer as a CSV list.
>>> pointer.to_csv()
[{'id': 'DataObjectPointer.field', 'value': '0x0'},
 {'id': 'DataObjectPointer.data.size', 'value': 0},
 {'id': 'DataObjectPointer.data.item', 'value': '0x0'}]

>>> # View the pointer field values as a JSON string.
>>> pointer.to_json()
'{"value": "0x0",
  "data": {"size": 0,
           "item": "0x0"}}'

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('DataObjectPointer.field', '0x0'),
 ('DataObjectPointer.data.size', 0),
 ('DataObjectPointer.data.item', '0x0')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'DataObjectPointer.field', 'value': '0x0'},
 {'id': 'DataObjectPointer.data.size', 'value': 0},
 {'id': 'DataObjectPointer.data.item', 'value': '0x0'}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x0",
  "data": {"size": 0,
           "item": {"value": "0x0",
                    "data": null}}}'

Nest Pointers

You can nest pointer.

>>> # Create a nested pointer with no data object attached.
>>> pointer = Pointer(Pointer())

>>> # List the field values of the pointer.
>>> pointer.to_list()
[('Pointer.field', '0x0'),
 ('Pointer.data', '0x0')]

>>> # List the field values of the pointer as a CSV list.
>>> pointer.to_csv()
[{'id': 'Pointer.field', 'value': '0x0'},
 {'id': 'Pointer.data', 'value': '0x0'}]

>>> # View the pointer field values as a JSON string.
>>> pointer.to_json()
'{"value": "0x0",
  "data": "0x0"}'

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x0'),
 ('Pointer.data', '0x0')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x0'},
 {'id': 'Pointer.data', 'value': '0x0'}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x0",
  "data": {"value": "0x0",
           "data": null}}'

>>> # Create a nested pointer with a data object attached.
>>> pointer = Pointer(Pointer(Byte()))

>>> # List the field values of the pointer.
>>> pointer.to_list()
[('Pointer.field', '0x0'),
 ('Pointer.data', '0x0')]

>>> # List the field values of the pointer as a CSV list.
>>> pointer.to_csv()
[{'id': 'Pointer.field', 'value': '0x0'},
 {'id': 'Pointer.data', 'value': '0x0'}]

>>> # View the pointer field values as a JSON string.
>>> pointer.to_json()
'{"value": "0x0",
  "data": "0x0"}'

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x0'),
 ('Pointer.data', '0x0'),
 ('Pointer.data.data', '0x0')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x0'},
 {'id': 'Pointer.data', 'value': '0x0'},
 {'id': 'Pointer.data.data', 'value': '0x0'}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x0",
  "data": {"value": "0x0",
           "data": "0x0"}}'

Access the Data Object

You can access the data object attached to a pointer with the data attribute of a pointer field.

>>> # Create a nested pointer.
>>> pointer = Pointer(Pointer(Byte()))

>>> # Index the pointer field and the fields of the attached data object.
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)

>>> # Access the data object referenced the pointer field.
>>> pointer.data
Pointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
        alignment=Alignment(byte_size=4, bit_offset=0),
        bit_size=32,
        value='0x0')

>>> # Access the data object referenced a nested pointer field.
>>> pointer.data.data
Byte(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
     alignment=Alignment(byte_size=1, bit_offset=0),
     bit_size=8,
     value='0x0')

You can check if a data object is a field.

>>> is_field(pointer.data)
True

You can check what kind of field it is.

>>> # Field is a bit field.
>>> pointer.data.is_bit()
False

>>> # Field is a boolean field.
>>> pointer.data.is_bool()
False

>>> # Field is a decimal field.
>>> pointer.data.is_decimal()
True

>>> # Field is a float field.
>>> pointer.data.is_float()
False

>>> # Field is a pointer field.
>>> pointer.data.is_pointer()
True

>>> # Field is a stream field.
>>> pointer.data.is_stream()
False

>>> # Field is a string field.
>>> pointer.data.is_string()
False

Address of the Data Object

You can get the data source address of the data object attached to the pointer with the address attribute of a pointer field.

>>> # Data source address of the data object referenced by the pointer.
>>> pointer.address
0

Byte Order of the Data Object

You can get the byte order used by the pointer to deserialize or serialize its attached data object with the data_byte_order attribute of a pointer field.

>>> # Byte order to de-/serialize the data object attached to the pointer.
>>> pointer.data_byte_order
Byteorder.little = 'little'
>>> pointer.data_byte_order.value
'little'

Note

The default byte order for a data object is little endian.

You can set the byte order used by the pointer to deserialize or serialize its attached data object with the data_byte_order attribute of a pointer field.

>>> # Set byte order to de-/serialize the data objects referenced by the pointer.
>>> pointer.data_byte_order = 'big'

>>> # Byte order to de-/serialize the data objects referenced by the pointer.
>>> pointer.data_byte_order
Byteorder.big = 'big'

Byte Stream for the Data Object

You can get the internal byte stream used by the pointer to deserialize or serialize its attached data object with the bytestream attribute of a pointer field.

>>> # Get the internal byte stream of the pointer.
>>> pointer.bytestream
''

You can set the internal byte stream used by the pointer to deserialize or serialize its attached data object with the bytestream attribute of a pointer field.

>>> # Set the internal byte stream of the pointer.
>>> pointer.bytestream = '000000000000'
>>> pointer.bytestream
'000000000000'

Declare on the fly

You can declare a data object on the fly.

>>> # Create a data object.
>>> data_object = Structure(
...     size = Decimal(16),
...     item = Pointer(String()))

>>> # List the field values of the data object.
>>> data_object.to_list()
[('Structure.size', 0),
 ('Structure.item', '0x0')]

>>> # List the field values of the data object as a CSV list.
>>> data_object.to_csv()
[{'id': 'Structure.size', 'value': 0},
 {'id': 'Structure.item', 'value': '0x0'}]

>>> # View the data object field values as a JSON string.
>>> data_object.to_json()
'{"size": 0, "item": "0x0"}'

>>> # List the field values of the data object and nested pointers.
>>> data_object.to_list(nested=True)
[('Structure.size', 0),
 ('Structure.item', '0x0'),
 ('Structure.item.data', '')]

>>> # List the field values of the data object and nested pointers as a CSV list.
>>> data_object.to_csv(nested=True)
[{'id': 'Structure.size', 'value': 0},
 {'id': 'Structure.item', 'value': '0x0'},
 {'id': 'Structure.item.data', 'value': ''}]

>>> # View the data object and nested pointers field values as a JSON string.
>>> data_object.to_json(nested=True)
'{"size": 0,
  "item": {"value": "0x0",
           "data": ""}}'

You can declare a pointer on the fly.

>>> # Create a pointer for the data object.
>>> pointer = Pointer(data_object)

>>> # List the field values of the pointer.
>>> pointer.to_list()
[('Pointer.field', '0x0'),
 ('Pointer.data.size', 0),
 ('Pointer.data.item', '0x0')]

>>> # List the field values of the pointer as a CSV list.
>>> pointer.to_csv()
[{'id': 'Pointer.field', 'value': '0x0'},
 {'id': 'Pointer.data.size', 'value': 0},
 {'id': 'Pointer.data.item', 'value': '0x0'}]

>>> # View the pointer field values as a JSON string.
>>> pointer.to_json()
'{"value": "0x0",
  "data": {"size": 0,
           "item": "0x0"}}'

>>> # List all field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x0'),
 ('Pointer.data.size', 0),
 ('Pointer.data.item', '0x0'),
 ('Pointer.data.item.data', '')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x0'},
 {'id': 'Pointer.data.size', 'value': 0},
 {'id': 'Pointer.data.item', 'value': '0x0'},
 {'id': 'Pointer.data.item.data', 'value': ''}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x0",
  "data": {"size": 0,
           "item": {"value": "0x0",
                    "data": ""}}}'

Initialize a Pointer

You can initialize the fields in a pointer by calling the method initialize_fields().

>>> # Create a pointer with a nested pointer.
>>> pointer = Pointer(
...     Structure(
...         size=Decimal(16),
...         item=Pointer(String(14))))

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x0'),
 ('Pointer.data.size', 0),
 ('Pointer.data.item', '0x0'),
 ('Pointer.data.item.data', '')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x0'},
 {'id': 'Pointer.data.size', 'value': 0},
 {'id': 'Pointer.data.item', 'value': '0x0'},
 {'id': 'Pointer.data.item.data', 'value': ''}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x0",
  "data": {"size": 0,
           "item": {"value": "0x0",
                    "data": ""}}}'

>>> # Initialize the fields values of the pointer and its attached data object.
>>> pointer.initialize_fields({
...     'value': 0x1,
...     'data': {
...         'size': 14,
...         'item': {
...             'value': 0x10,
...             'data': 'Konfoo is Fun'
...         }
...     }
... })

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x1'),
 ('Pointer.data.size', 14),
 ('Pointer.data.item', '0x10'),
 ('Pointer.data.item.data', 'Konfoo is Fun')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x1'},
 {'id': 'Pointer.data.size', 'value': 14},
 {'id': 'Pointer.data.item', 'value': '0x10'},
 {'id': 'Pointer.data.item.data', 'value': 'Konfoo is Fun'}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x1",
  "data": {"size": 14,
           "item": {"value": "0x10",
                    "data": "Konfoo is Fun"}}}'

Display a Pointer

You can display a pointer field.

>>> # Create a pointer.
>>> pointer = Pointer(
...     Structure(
...         size=Decimal(16),
...         item=Pointer(String())))

>>> # Index the pointer field and its attached data object.
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)

>>> # Display the pointer field.
>>> pointer
Pointer(index=Index(byte=0, bit=0,
                    address=0, base_address=0,
                    update=False),
        alignment=Alignment(byte_size=4, bit_offset=0),
        bit_size=32,
        value='0x0')

Display the Data Object

You can display the data object of a pointer field.

>>> # Display the data object referenced by the pointer.
>>> pointer.data  
{'size': Decimal(
    index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
    alignment=Alignment(byte_size=2, bit_offset=0),
    bit_size=16,
    value=0),
 'item': Pointer(
    index=Index(byte=2, bit=0, address=2, base_address=0, update=False),
    alignment=Alignment(byte_size=4, bit_offset=0),
    bit_size=32,
    value='0x0')}
>>>

Metadata of a Pointer

You can get the metadata of a pointer by calling the method describe().

A dict with the metadata of the pointer is returned

>>> # Get the metadata of the pointer.
>>> pointer.describe()  
{'address': 0,
 'alignment': [4, 0],
 'class': 'Pointer',
 'index': [0, 0],
 'max': 4294967295,
 'min': 0,
 'name': 'Pointer',
 'order': 'auto',
 'signed': False,
 'size': 32,
 'type': 'Pointer',
 'value': '0x0',
 'member': [
    {'class': 'Structure',
     'name': 'data',
     'size': 2,
     'type': 'Structure',
     'member': [
        {'address': 0,
         'alignment': [2, 0],
         'class': 'Decimal16',
         'index': [0, 0],
         'max': 65535,
         'min': 0,
         'name': 'size',
         'order': 'auto',
         'signed': False,
         'size': 16,
         'type': 'Field',
         'value': 0},
        {'address': 2,
         'alignment': [4, 0],
         'class': 'Pointer',
         'index': [2, 0],
         'max': 4294967295,
         'min': 0,
         'name': 'item',
         'order':'auto',
         'signed': False,
         'size': 32,
         'type': 'Pointer',
         'value': '0x0',
         'member': [
            {'address': 0,
             'alignment': [0, 0],
             'class': 'String',
             'index': [0, 0],
             'name': 'data',
             'order': 'auto',
             'size': 0,
             'type': 'Field',
             'value': ''}]}]}]}

>>> # Dump the metadata of the pointer as a JSON string to the console.
>>> json.dump(pointer.describe(), sys.stdout, indent=2)
{
  "address": 0,
  "alignment": [
    4,
    0
  ],
  "class": "Pointer",
  "index": [
    0,
    0
  ],
  "max": 4294967295,
  "min": 0,
  "name": "Pointer",
  "order": "auto",
  "signed": false,
  "size": 32,
  "type": "Pointer",
  "value": "0x0",
  "member": [
    {
      "class": "Structure",
      "name": "data",
      "size": 2,
      "type": "Structure",
      "member": [
        {
          "address": 0,
          "alignment": [
            2,
            0
          ],
          "class": "Decimal16",
          "index": [
            0,
            0
          ],
          "max": 65535,
          "min": 0,
          "name": "size",
          "order": "auto",
          "signed": false,
          "size": 16,
          "type": "Field",
          "value": 0
        },
        {
          "address": 2,
          "alignment": [
            4,
            0
          ],
          "class": "Pointer",
          "index": [
            2,
            0
          ],
          "max": 4294967295,
          "min": 0,
          "name": "item",
          "order": "auto",
          "signed": false,
          "size": 32,
          "type": "Pointer",
          "value": "0x0",
          "member": [
            {
              "address": 0,
              "alignment": [
                0,
                0
              ],
              "class": "String",
              "index": [
                0,
                0
              ],
              "name": "data",
              "order": "auto",
              "size": 0,
              "type": "Field",
              "value": ""
            }
          ]
        }
      ]
    }
  ]
}

Size of the Data Object

You can get the byte size of the data object attached to the pointer with the data_size attribute of a pointer field.

>>> # Byte size of the data object attached to the pointer.
>>> pointer.data_size
6

Indexing

You can index the pointer field and each field of the data object attached to the pointer field by calling the method index_fields().

The Index after the pointer field is returned.

>>> # Create a pointer with a nested pointer.
>>> pointer = Pointer(
...     Structure(
...         size=Decimal(16),
...         item=Pointer(String(14))))

>>> # Initialize the fields values.
>>> pointer.initialize_fields({
...     'value': 0x1,
...     'data': {
...         'size': 14,
...         'item': {
...             'value': 0x10,
...             'data': 'Konfoo is Fun'}}})

>>> # List the field indexes of the pointer and nested pointers.
>>> pointer.to_list('index', nested=True)
[('Pointer.field',
 Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.size',
 Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.item',
 Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.item.data',
 Index(byte=0, bit=0, address=0, base_address=0, update=False))]

>>> # List the field indexes of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv('index.byte', 'index.address', nested=True)
[{'id': 'Pointer.field', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.size', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.item', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.item.data', 'index.byte': 0, 'index.address': 0}]

>>> # View the pointer and nested pointers field indexes as a JSON string.
>>> pointer.to_json('index', nested=True)
'{"value": [0, 0, 0, 0, false],
  "data": {"size": [0, 0, 0, 0, false],
           "item": {"value": [0, 0, 0, 0, false],
                    "data": [0, 0, 0, 0, false]}}}'

>>> # Index the pointer field and the data object fields.
>>> pointer.index_fields()
Index(byte=4, bit=0, address=4, base_address=0, update=False)

>>> # Index the pointer field and the data object fields with a start index.
>>> pointer.index_fields(index=Index())
Index(byte=4, bit=0, address=4, base_address=0, update=False)

>>> # List the field indexes of the pointer and nested pointers.
>>> pointer.to_list('index', nested=True)
 [('Pointer.field',
  Index(byte=0, bit=0, address=0, base_address=0, update=False)),
  ('Pointer.data.size',
  Index(byte=0, bit=0, address=1, base_address=1, update=False)),
  ('Pointer.data.item',
  Index(byte=2, bit=0, address=3, base_address=1, update=False)),
  ('Pointer.data.item.data',
  Index(byte=0, bit=0, address=0, base_address=0, update=False))]

>>> # List the field indexes of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv('index.byte', 'index.address', nested=True)
[{'id': 'Pointer.field', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.size', 'index.byte': 0, 'index.address': 1},
 {'id': 'Pointer.data.item', 'index.byte': 2, 'index.address': 3},
 {'id': 'Pointer.data.item.data', 'index.byte': 0, 'index.address': 0}]

>>> # View the pointer and nested pointers field indexes as a JSON string.
>>> pointer.to_json('index', nested=True)
'{"value": [0, 0, 0, 0, false],
  "data": {"size": [0, 0, 1, 1, false],
           "item": {"value": [2, 0, 3, 1, false],
                    "data": [0, 0, 0, 0, false]}}}'

>>> # Index the pointer field and the fields of the data object and nested pointers.
>>> pointer.index_fields(nested=True)
Index(byte=4, bit=0, address=4, base_address=0, update=False)

>>> # List the field indexes of the pointer and nested pointers.
>>> pointer.to_list('index', nested=True)
[('Pointer.field',
  Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.size',
  Index(byte=0, bit=0, address=1, base_address=1, update=False)),
 ('Pointer.data.item',
  Index(byte=2, bit=0, address=3, base_address=1, update=False)),
 ('Pointer.data.item.data',
  Index(byte=0, bit=0, address=16, base_address=16, update=False))]

>>> # List the field indexes of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv('index.byte', 'index.address', nested=True)
[{'id': 'Pointer.field', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.size', 'index.byte': 0, 'index.address': 1},
 {'id': 'Pointer.data.item', 'index.byte': 2, 'index.address': 3},
 {'id': 'Pointer.data.item.data', 'index.byte': 0, 'index.address': 16}]

>>> # View the pointer and nested pointers field indexes as a JSON string.
>>> pointer.to_json('index', nested=True)
'{"value": [0, 0, 0, 0, false],
  "data": {"size": [0, 0, 1, 1, false],
           "item": {"value": [2, 0, 3, 1, false],
                    "data": [0, 0, 16, 16, false]}}}'

Index the Pointer Field

You can index the pointer field by calling the method index_field().

The Index after the pointer field is returned.

>>> # Create a pointer.
>>> pointer = Pointer(
...     Structure(
...         size=Decimal(16),
...         item=Pointer(String(14))))

>>> # Initialize the fields values.
>>> pointer.initialize_fields({
...     'value': 0x1,
...     'data': {
...         'size': 14,
...         'item': {
...             'value': 0x10,
...             'data': 'Konfoo is Fun'}}})

>>> # List the field indexes of the pointer and nested pointers.
>>> pointer.to_list('index', nested=True)
[('Pointer.field',
 Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.size',
 Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.item',
 Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.item.data',
 Index(byte=0, bit=0, address=0, base_address=0, update=False))]

>>> # List the field indexes of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv('index.byte', 'index.address', nested=True)
[{'id': 'Pointer.field', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.size', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.item', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.item.data', 'index.byte': 0, 'index.address': 0}]

>>> # View the pointer and nested pointers field indexes as a JSON string.
>>> pointer.to_json('index', nested=True)
'{"value": [0, 0, 0, 0, false],
  "data": {"size": [0, 0, 0, 0, false],
           "item": {"value": [0, 0, 0, 0, false],
                    "data": [0, 0, 0, 0, false]}}}'

>>> # Index the pointer field.
>>> pointer.index_field()
Index(byte=4, bit=0, address=4, base_address=0, update=False)

>>> # Index the pointer field with a start index.
>>> pointer.index_field(index=Index())
Index(byte=4, bit=0, address=4, base_address=0, update=False)

>>> # List the field indexes of the pointer and nested pointers.
>>> pointer.to_list('index', nested=True)
[('Pointer.field',
 Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.size',
 Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.item',
 Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.item.data',
 Index(byte=0, bit=0, address=0, base_address=0, update=False))]

>>> # List the field indexes of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv('index.byte', 'index.address', nested=True)
[{'id': 'Pointer.field', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.size', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.item', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.item.data', 'index.byte': 0, 'index.address': 0}]

>>> # View the pointer and nested pointers field indexes as a JSON string.
>>> pointer.to_json('index', nested=True)
'{"value": [0, 0, 0, 0, false],
  "data": {"size": [0, 0, 0, 0, false],
           "item": {"value": [0, 0, 0, 0, false],
                    "data": [0, 0, 0, 0, false]}}}'

Index the Data Object

You can index each field of the data object attached to the pointer field by calling the method index_data()

>>> # Create a pointer with a nested pointer.
>>> pointer = Pointer(
...     Structure(
...         size=Decimal(16),
...         item=Pointer(String(14))))

>>> # Initialize the fields values.
>>> pointer.initialize_fields({
...     'value': 0x1,
...     'data': {
...         'size': 14,
...         'item': {
...             'value': 0x10,
...             'data': 'Konfoo is Fun'}}})

>>> # List the field indexes of the pointer and nested pointers.
>>> pointer.to_list('index', nested=True)
[('Pointer.field',
  Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.size',
  Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.item',
  Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.item.data',
 Index(byte=0, bit=0, address=0, base_address=0, update=False))]

>>> # List the field indexes of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv('index.byte', 'index.address', nested=True)
[{'id': 'Pointer.field', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.size', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.item', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.item.data', 'index.byte': 0, 'index.address': 0}]

>>> # View the pointer and nested pointers field indexes as a JSON string.
>>> pointer.to_json('index', nested=True)
'{"value": [0, 0, 0, 0, false],
  "data": {"size": [0, 0, 0, 0, false],
           "item": {"value": [0, 0, 0, 0, false],
                    "data": [0, 0, 0, 0, false]}}}'

>>> # Index the data object and nested pointers of the pointer.
>>> pointer.index_data()

>>> # List the field indexes of the pointer and nested pointers.
>>> pointer.to_list('index', nested=True)
[('Pointer.field',
  Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.size',
  Index(byte=0, bit=0, address=1, base_address=1, update=False)),
 ('Pointer.data.item',
  Index(byte=2, bit=0, address=3, base_address=1, update=False)),
 ('Pointer.data.item.data',
 Index(byte=0, bit=0, address=16, base_address=16, update=False))]

>>> # List the field indexes of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv('index.byte', 'index.address', nested=True)
[{'id': 'Pointer.field', 'index.byte': 0, 'index.address': 0},
 {'id': 'Pointer.data.size', 'index.byte': 0, 'index.address': 1},
 {'id': 'Pointer.data.item', 'index.byte': 2, 'index.address': 3},
 {'id': 'Pointer.data.item.data', 'index.byte': 0, 'index.address': 16}]

>>> # View the pointer and nested pointers field indexes as a JSON string.
>>> pointer.to_json('index', nested=True)
'{"value": [0, 0, 0, 0, false],
  "data": {"size": [0, 0, 1, 1, false],
           "item": {"value": [2, 0, 3, 1, false],
                    "data": [0, 0, 16, 16, false]}}}'

Reading

You can read the byte stream used by the pointer to deserialize its attached data object from a data source through a byte stream provider by calling the method read_from() of a pointer field.

Note

Further information is provided by the reading chapter.

De-Serializing

You can deserialize the pointer field from a byte stream and the attached data object from the internal byte stream of a pointer by calling the method deserialize().

>>> # Create a pointer with a nested pointer.
>>> pointer = Pointer(
...     Structure(
...         size=Decimal(16),
...         item=Pointer(String(14))))

>>> # List the field values of the pointer and nested pointers
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x0'),
 ('Pointer.data.size', 0),
 ('Pointer.data.item', '0x0'),
 ('Pointer.data.item.data', '')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x0'},
 {'id': 'Pointer.data.size', 'value': 0},
 {'id': 'Pointer.data.item', 'value': '0x0'},
 {'id': 'Pointer.data.item.data', 'value': ''}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x0",
  "data": {"size": 0,
           "item": {"value": "0x0",
                    "data": ""}}}'

>>> # Internal byte stream of the pointer
>>> pointer.bytestream
''

>>> # Internal byte stream of the nested pointer
>>> pointer.data.item.bytestream
''

>>> # Deserialize the pointer field from the byte stream.
>>> pointer.deserialize(bytes.fromhex('01000000f00f00'))
Index(byte=4, bit=0, address=4, base_address=0, update=False)

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x1'),
 ('Pointer.data.size', 0),
 ('Pointer.data.item', '0x0'),
 ('Pointer.data.item.data', '')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x1'},
 {'id': 'Pointer.data.size', 'value': 0},
 {'id': 'Pointer.data.item', 'value': '0x0'},
 {'id': 'Pointer.data.item.data', 'value': ''}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x1",
  "data": {"size": 0,
           "item": {"value": "0x0",
                    "data": ""}}}'

>>> # Set the internal byte stream of the pointer
>>> pointer.bytestream = '0e0010000000'

>>> # Set the internal byte stream of the nested pointer
>>> pointer.data.item.bytestream = '4b6f6e666f6f2069732046756e00f00f00'

>>> # Deserialize the pointer and nested pointers from the internal byte streams.
>>> pointer.deserialize(bytes.fromhex('01000000f00f00'), nested=True)
Index(byte=4, bit=0, address=4, base_address=0, update=False)

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x1'),
 ('Pointer.data.size', 14),
 ('Pointer.data.item', '0x10'),
 ('Pointer.data.item.data', 'Konfoo is Fun')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x1'},
 {'id': 'Pointer.data.size', 'value': 14},
 {'id': 'Pointer.data.item', 'value': '0x10'},
 {'id': 'Pointer.data.item.data', 'value': 'Konfoo is Fun'}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x1",
  "data": {"size": 14,
           "item": {"value": "0x10",
                    "data": "Konfoo is Fun"}}}'

Deserialize the Data Object

You can deserialize the data object attached to the pointer by calling the method deserialize_data() of a pointer field.

>>> # Create a pointer with a nested pointer.
>>> pointer = Pointer(
...     Structure(
...         size=Decimal(16),
...         item=Pointer(String(14))),
...     address=1)

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x1'),
 ('Pointer.data.size', 0),
 ('Pointer.data.item', '0x0'),
 ('Pointer.data.item.data', '')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x1'},
 {'id': 'Pointer.data.size', 'value': 0},
 {'id': 'Pointer.data.item', 'value': '0x0'},
 {'id': 'Pointer.data.item.data', 'value': ''}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x1",
  "data": {"size": 0,
           "item": {"value": "0x0",
                    "data": ""}}}'

>>> # Internal byte stream of the pointer.
>>> pointer.bytestream
''

>>> # Set the internal byte stream of the nested pointer.
>>> pointer.data.item.bytestream = '4b6f6e666f6f2069732046756e00'

>>> # Deserialize the data object of the pointer from an external byte stream.
>>> pointer.deserialize_data(bytes.fromhex('0e0010000000'))
Index(byte=6, bit=0, address=7, base_address=1, update=False)

>>> # Internal byte stream of the pointer.
>>> pointer.bytestream
''

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x1'),
 ('Pointer.data.size', 14),
 ('Pointer.data.item', '0x10'),
 ('Pointer.data.item.data', '')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x1'},
 {'id': 'Pointer.data.size', 'value': 14},
 {'id': 'Pointer.data.item', 'value': '0x10'},
 {'id': 'Pointer.data.item.data', 'value': ''}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x1",
  "data": {"size": 14,
           "item": {"value": "0x10",
                    "data": ""}}}'

>>> # Deserialize the data object of the nested pointer from the internal byte stream.
>>> pointer.data.item.deserialize_data()
Index(byte=14, bit=0, address=30, base_address=16, update=False)

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x1'),
 ('Pointer.data.size', 14),
 ('Pointer.data.item', '0x10'),
 ('Pointer.data.item.data', 'Konfoo is Fun')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x1'},
 {'id': 'Pointer.data.size', 'value': 14},
 {'id': 'Pointer.data.item', 'value': '0x10'},
 {'id': 'Pointer.data.item.data', 'value': 'Konfoo is Fun'}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x1",
  "data": {"size": 14,
           "item": {"value": "0x10",
                    "data": "Konfoo is Fun"}}}'

Serializing

You can serialize the pointer field to a byte stream and the attached data object to the internal byte stream of a pointer by calling the method serialize().

>>> # Create a pointer with a nested pointer.
>>> pointer = Pointer(
...     Structure(
...         size=Decimal(16),
...         item=Pointer(String(14))))

>>> # Initialize the fields values.
>>> pointer.initialize_fields({
...     'value': 0x1,
...     'data': {
...         'size': 14,
...         'item': {
...             'value': 0x10,
...             'data': 'Konfoo is Fun'}}})

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x1'),
 ('Pointer.data.size', 14),
 ('Pointer.data.item', '0x10'),
 ('Pointer.data.item.data', 'Konfoo is Fun')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x1'},
 {'id': 'Pointer.data.size', 'value': 14},
 {'id': 'Pointer.data.item', 'value': '0x10'},
 {'id': 'Pointer.data.item.data', 'value': 'Konfoo is Fun'}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x1",
  "data": {"size": 14,
           "item": {"value": "0x10",
                    "data": "Konfoo is Fun"}}}'

>>> # Internal byte stream of the pointer.
>>> pointer.bytestream
''

>>> # Internal byte stream of the nested pointer.
>>> pointer.data.item.bytestream
''

>>> # Byte stream for the serialized pointer field.
>>> bytestream = bytearray()

>>> # Serialize the pointer field to the byte stream
>>> pointer.serialize(bytestream)
Index(byte=4, bit=0, address=4, base_address=0, update=False)

>>> # Internal byte stream of the pointer.
>>> pointer.bytestream
''

>>> # Internal byte stream of the nested pointer.
>>> pointer.data.item.bytestream
''

>>> # Serialized pointer field
>>> bytestream.hex()
'01000000'

>>> # Serialized pointer field
>>> bytes(pointer).hex()
'01000000'

>>> # Byte stream for the serialized pointer field.
>>> bytestream = bytearray()

>>> # Serialize the pointer and nested pointers to the internal byte streams
>>> pointer.serialize(bytestream, nested=True)
Index(byte=4, bit=0, address=4, base_address=0, update=False)

>>> # Internal byte stream of the pointer.
>>> pointer.bytestream
'0e0010000000'

>>> # Internal byte stream of the nested pointer.
>>> pointer.data.item.bytestream
'4b6f6e666f6f2069732046756e00'

>>> # Serialized pointer field
>>> bytestream.hex()
'01000000'

>>> # Serialized pointer field
>>> bytes(pointer).hex()
'01000000'

Serialize the Data Object

You can serialize the data object attached to the pointer by calling the method serialize_data() of a pointer field.

>>> # Create a pointer with a nested pointer.
>>> pointer = Pointer(
...     Structure(
...         size=Decimal(16),
...         item=Pointer(String(14))))

>>> # Initialize the fields values.
>>> pointer.initialize_fields({
...     'value': 0x1,
...     'data': {
...         'size': 14,
...         'item': {
...             'value': 0x10,
...             'data': 'Konfoo is Fun'}}})

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x1'),
 ('Pointer.data.size', 14),
 ('Pointer.data.item', '0x10'),
 ('Pointer.data.item.data', 'Konfoo is Fun')]

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x1'},
 {'id': 'Pointer.data.size', 'value': 14},
 {'id': 'Pointer.data.item', 'value': '0x10'},
 {'id': 'Pointer.data.item.data', 'value': 'Konfoo is Fun'}]

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x1",
  "data": {"size": 14,
           "item": {"value": "0x10",
                    "data": "Konfoo is Fun"}}}'

>>> # Internal byte stream of the pointer.
>>> pointer.bytestream
''

>>> # Internal byte stream of the nested pointer.
>>> pointer.data.item.bytestream
''

>>> # Serialize the data object of the pointer.
>>> pointer.serialize_data().hex()
'0e0010000000'

>>> # Internal byte stream of the pointer.
>>> pointer.bytestream
''

>>> # Serialize the data object of the nested pointer.
>>> pointer.data.item.serialize_data().hex()
'4b6f6e666f6f2069732046756e00'

>>> # Internal byte stream of the nested pointer.
>>> pointer.data.item.bytestream
''

Writing

You can write the field value of any field or the field values of any container of the data object attached to a pointer to a data source through a byte stream provider by calling method write_to() of a pointer field.

Note

Further information is provided by the writing chapter.

Attributes of a Pointer Field

You can access the field attributes of a pointer field with the following attribute names:

>>> # Field name.
>>> pointer.name
'Pointer32'

>>> # Field value.
>>> pointer.value
'0x1'

>>> # Field bit size.
>>> pointer.bit_size
32

>>> # Field alignment.
>>> pointer.alignment
Alignment(byte_size=4, bit_offset=0)

>>> # Field alignment: byte size of the aligned field group.
>>> pointer.alignment.byte_size
4

>>> # Field alignment: bit offset of the field in its field group.
>>> pointer.alignment.bit_offset
0

>>> # Field byte order.
>>> pointer.byte_order
Byteorder.auto = 'auto'

>>> # Field byte order value.
>>> pointer.byte_order.value
'auto'

>>> # Field index.
>>> pointer.index
Index(byte=0, bit=0, address=0, base_address=0, update=False)

>>> # Field index: byte offset of the field in the byte stream.
>>> pointer.index.byte
0

>>> # Field index: bit offset of the field relative to its byte offset.
>>> pointer.index.bit
0

>>> # Field index: memory address of the field in the data source.
>>> pointer.index.address
0

>>> # Field index: start address of the byte stream in the data source.
>>> pointer.index.base_address
0

>>> # Field index: update request for the byte stream.
>>> pointer.index.update
False

You can check if a pointer is a Null-pointer.

>>> # Field points to zero.
>>> pointer.is_null()
False

View Field Attributes

You can view the attributes of a pointer field and of each field of the data object attached to the pointer field as a dictionary by calling the method view_fields().

The default attribute is the field value.

>>> # View the pointer field values.
>>> pointer.view_fields()
{'value': '0x1', 'data': {'size': 14, 'item': '0x10'}}

>>> # View the pointer and nested pointers field values.
>>> pointer.view_fields(nested=True)  
{'value': '0x1',
  'data': {
    'size': 14,
    'item': {
        'value': '0x10',
        'data': 'Konfoo is Fun'}}}

>>> # View the pointer field type names & field values.
>>> pointer.view_fields('name', 'value')  
{'name': 'Pointer32',
 'value': '0x1',
 'data': {
    'size': {'name': 'Decimal16', 'value': 14},
    'item': {'name': 'Pointer32', 'value': '0x10'}}}

>>> # View the pointer field indexes.
>>> pointer.view_fields('index')  
{'value': Index(byte=0, bit=0, address=0, base_address=0, update=False),
 'data': {
    'size': Index(byte=0, bit=0, address=1, base_address=1, update=False),
    'item': Index(byte=2, bit=0, address=3, base_address=1, update=False)}
}

View as a JSON string

You can view the attributes of a pointer field and of each field of the data object attached to the pointer field as a JSON formatted string by calling the method to_json(). Default attribute is the field value.

>>> # View the pointer field values as a JSON string.
>>> pointer.to_json()
'{"value": "0x1",
  "data": {"size": 14,
           "item": "0x10"}}'
>>> print(pointer.to_json(indent=2))
{
  "value": "0x1",
  "data": {
    "size": 14,
    "item": "0x10"
  }
}

>>> # View the pointer and nested pointers field values as a JSON string.
>>> pointer.to_json(nested=True)
'{"value": "0x1",
  "data": {"size": 14,
           "item": {"value": "0x10",
                    "data": "Konfoo is Fun"}}}'

>>> # View the pointer field type names & field values as a JSON string.
>>> pointer.to_json('name', 'value')
'{"name": "Pointer32",
  "value": "0x1",
  "data": {"size": {"name": "Decimal16",
                    "value": 14},
           "item": {"name": "Pointer32",
                    "value": "0x10"}}}'

>>> # View the pointer field indexes as a JSON string.
>>> pointer.to_json('index')
'{"value": [0, 0, 0, 0, false],
  "data": {"size": [0, 0, 1, 1, false],
           "item": [2, 0, 3, 1, false]}}'

List Field Items

You can list all field items of a pointer as a flatten list by calling the method field_items().

>>> # List the field items of the pointer.
>>> pointer.field_items()
[('field',
  Pointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
          alignment=Alignment(byte_size=4, bit_offset=0),
          bit_size=32,
          value='0x1')),
 ('data.size',
  Decimal(index=Index(byte=0, bit=0, address=1, base_address=1, update=False),
          alignment=Alignment(byte_size=2, bit_offset=0),
          bit_size=16,
          value=14)),
 ('data.item',
  Pointer(index=Index(byte=2, bit=0, address=3, base_address=1, update=False),
          alignment=Alignment(byte_size=4, bit_offset=0),
          bit_size=32,
          value='0x10'))]

>>> # List the field items of the pointer and nested pointers.
>>> pointer.field_items(nested=True)
[('field',
  Pointer(index=Index(byte=0, bit=0, address=0, base_address=0, update=False),
          alignment=Alignment(byte_size=4, bit_offset=0),
          bit_size=32,
          value='0x1')),
 ('data.size',
  Decimal(index=Index(byte=0, bit=0, address=1, base_address=1, update=False),
          alignment=Alignment(byte_size=2, bit_offset=0),
          bit_size=16,
          value=14)),
 ('data.item',
  Pointer(index=Index(byte=2, bit=0, address=3, base_address=1, update=False),
          alignment=Alignment(byte_size=4, bit_offset=0),
          bit_size=32,
          value='0x10')),
 ('data.item.data',
  String(index=Index(byte=0, bit=0, address=16, base_address=16, update=False),
         alignment=Alignment(byte_size=14, bit_offset=0),
         bit_size=112,
         value='Konfoo is Fun'))]

List Field Attributes

You can list the attributes of each field of a pointer as a flatten list by calling the method to_list().

The default attribute is the field value.

>>> # List the field values of the pointer and its attached data object.
>>> pointer.to_list()
[('Pointer.field', '0x1'),
 ('Pointer.data.size', 14),
 ('Pointer.data.item', '0x10')]

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x1'),
 ('Pointer.data.size', 14),
 ('Pointer.data.item', '0x10'),
 ('Pointer.data.item.data', 'Konfoo is Fun')]

>>> # List the field type names & values of the pointer and its attached data object.
>>> pointer.to_list('name', 'value')
[('Pointer.field', ('Pointer32', '0x1')),
 ('Pointer.data.size', ('Decimal16', 14)),
 ('Pointer.data.item', ('Pointer32', '0x10'))]

>>> # List the field indexes of the pointer and its attached data object.
>>> pointer.to_list('index')
[('Pointer.field',
  Index(byte=0, bit=0, address=0, base_address=0, update=False)),
 ('Pointer.data.size',
  Index(byte=0, bit=0, address=1, base_address=1, update=False)),
 ('Pointer.data.item',
  Index(byte=2, bit=0, address=3, base_address=1, update=False))]

Note

The class name of the instance is used for the root name as long as no name is given.

You can list the attributes of each field of a pointer as a flatten dictionary by calling the method to_dict().

The default attribute is the field value.

>>> # List the field values of the pointer and its attached data object.
>>> pointer.to_dict()
{'Pointer': {'field': '0x1', 'data.size': 14, 'data.item': '0x10'}}

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_dict(nested=True)  
{'Pointer': {
 'field': '0x1',
 'data.size': 14,
 'data.item': '0x10',
 'data.item.data': 'Konfoo is Fun'}
}

>>> # List the field type names & values of the pointer and its attached data object.
>>> pointer.to_dict('name', 'value')  
{'Pointer': {
 'field': ('Pointer32', '0x1'),
 'data.size': ('Decimal16', 14),
 'data.item': ('Pointer32', '0x10')}
}

>>> # List the field indexes of the pointer and its attached data object.
>>> pointer.to_dict('index')  
{'Pointer': {
 'field': Index(byte=0, bit=0, address=0, base_address=0, update=False),
 'data.size': Index(byte=0, bit=0, address=1, base_address=1, update=False),
 'data.item': Index(byte=2, bit=0, address=3, base_address=1, update=False)}
}

Note

The class name of the instance is used for the root name as long as no name is given.

You can list the attributes of each field of a pointer as a flatten list of dictionaries containing the field path and the selected field attributes by calling the method to_csv().

The default attribute is the field value.

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x1'},
 {'id': 'Pointer.data.size', 'value': 14},
 {'id': 'Pointer.data.item', 'value': '0x10'},
 {'id': 'Pointer.data.item.data', 'value': 'Konfoo is Fun'}]

>>> # List the field type names & values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv('name', 'value', nested=True)
[{'id': 'Pointer.field', 'name': 'Pointer32', 'value': '0x1'},
 {'id': 'Pointer.data.size', 'name': 'Decimal16', 'value': 14},
 {'id': 'Pointer.data.item', 'name': 'Pointer32', 'value': '0x10'},
 {'id': 'Pointer.data.item.data', 'name': 'String14', 'value': 'Konfoo is Fun'}]

Note

The class name of the instance is used for the root name as long as no name is given.

Write Field Attributes

You can write the attributes of each field of a pointer to a .csv file by calling the method write_csv().

The default attribute is the field value.

>>> # List the field values of the pointer and nested pointers as a CSV list.
>>> pointer.to_csv(nested=True)
[{'id': 'Pointer.field', 'value': '0x1'},
 {'id': 'Pointer.data.size', 'value': 14},
 {'id': 'Pointer.data.item', 'value': '0x10'},
 {'id': 'Pointer.data.item.data', 'value': 'Konfoo is Fun'}]

>>> # Save the structure field values to a '.csv' file.
>>> pointer.write_csv("./_static/pointer.csv", nested=True)

The generated .csv file for the structure looks like this:

id,value
Pointer.field,0x1
Pointer.data.size,14
Pointer.data.item,0x10
Pointer.data.item.data,Konfoo is Fun

Note

The class name of the instance is used for the root name as long as no name is given.

Save Field Attributes

You can save the attributes of each field of a pointer to an .ini file by calling the method save().

The default attribute is the field value.

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x1'),
 ('Pointer.data.size', 14),
 ('Pointer.data.item', '0x10'),
 ('Pointer.data.item.data', 'Konfoo is Fun')]

>>> # Save the pointer and nested pointers field values to an '.ini' file.
>>> pointer.save("./_static/pointer.ini", nested=True)

The generated .ini file for the pointer looks like this:

[Pointer]
field = 0x1
data.size = 14
data.item = 0x10
data.item.data = Konfoo is Fun

Note

The class name of the instance is used for the section name as long as no section is given.

Load Field Values

You can load the values of each field of a pointer from an .ini file by calling the method load().

>>> # Load the pointer and nested pointers field values from an '.ini' file.
>>> pointer.load("./_static/pointer.ini", nested=True)
[Pointer]
Pointer.field = 0x1
Pointer.data.size = 14
Pointer.data.item = 0x10
Pointer.data.item.data = Konfoo is Fun

>>> # List the field values of the pointer and nested pointers.
>>> pointer.to_list(nested=True)
[('Pointer.field', '0x1'),
 ('Pointer.data.size', 14),
 ('Pointer.data.item', '0x10'),
 ('Pointer.data.item.data', 'Konfoo is Fun')]

Note

The class name of the instance is used for the section name as long as no section is given.