Additional Documentation and Examples

[zachriggle]

It would be great if PFP had more documentation and examples about how to use it.

Consider:

import pfp

data='\xff\x08\x00\x00\x00DATADATA'

template='''
struct foo {
  uchar byte1;
  uint32 word2;
  uchar data[word2];
};
foo bar;
'''

dom = pfp.parse(data, template)

There doesn't appear to be any documentation on how to interact with the dom object and introspect. All I can do is iterate through it, and even that's not clear on the types I'm iterating through. dir() and __dict__ and other means of introspection don't show any useful fields with which data can be extracted.

for struct in dom:
    for item in struct:
        print(item)
"""
UChar(255 [ff])
UInt(8 [00000008])
UChar[8] ('DATADATA')
"""

It would be nice to be able to print something out like the names of the fields, and possibly have access to whatever field the length came from. For example, something like:

struct type=foo name=bar
  var type=uchar name=byte1 value=0xff
  var type=uint32 name=word2 value=0x00000008
  var type=??? name=data value="DATADATA" length=8 length_obj=<reference to word2>

Separately, it would be nice to be able to introspect into the compiled template and iterate over the structures / data types without providing exemplar data. Clearly this won't work when there are control-flow statements and conditionally-declared data types, but for plain lists of structs / fields / fields-with-variable-length, this should be possible.

Ultimately I want to use PFP to automatically generate ASCII diagrams from structure definitions, so I need access to the struct/field name, size, and a reference to the corresponding e.g. length field for a variable-width array.

[d0c-s4vage]

@zachriggle Finally spinning back up on this project. Thank you for opening this issue!

Separately, it would be nice to be able to introspect into the compiled template and iterate over the structures / data types without providing exemplar data.

I think you should be able to actually... more documentation on working with this would definitely be useful.

Ultimately I want to use PFP to automatically generate ASCII diagrams from structure definitions, so I need access to the struct/field name, size, and a reference to the corresponding e.g. length field for a variable-width array.

Definitely doable! I'll work on better documentation for this this week.