Fields¶
General¶
Every declared variable in 010 templates creates a pfp.fields.Field
instance in memory.
Naming Convention¶
Some may find it annoying having the prefix _pfp__
affixed to field methods
and variables, but I found it more annoying having to access all child fields
of a struct via square brackets. The prefix is simply to prevent name collisions
so that __getattr__
can be used to access child fields with dot-notation.
Parsed Offset¶
Parsed offsets of fields are set during object parsing and are re-set each time
the main pfp.fields.Dom
instance is built. This means that operations
that should modify the offsets of fields will cause invalid offsets to exist
until the main dom is built again.
Printing¶
Use the pfp.fields.Field._pfp__show
method to return a
pretty-printed representation of the field.
Full Field Paths¶
Use the pfp.fields.Field._pfp__path
method to fetch the full path
of the field. E.g. in the template below, the inner
field would have
a full path of root.nested1.nested2.inner
, and the second element of
the array
field would have a full path of root.nested1.nested2.array[1]
:
struct {
struct {
struct {
char inner;
char array[4];
} nested2;
int some_int;
} nested1;
int some_int2;
} root;
Structs¶
Structs are the main containers used to add fields to. A pfp.fields.Dom
instance
is the struct that all fields are added to.
Field Reference Documentation¶
-
class
pfp.fields.
Field
(stream=None, metadata_processor=None)[source]¶ Core class for all fields used in the Pfp DOM.
All methods use the _pfp__XXX naming convention to avoid conflicting names used in templates, since struct fields will implement
__getattr__
and__setattr__
to directly access child fields-
_pfp__build
(output_stream=None, save_offset=False)[source]¶ Pack this field into a string. If output_stream is specified, write the output into the output stream
Output_stream: Optional output stream to write the results to Save_offset: If true, the current offset into the stream will be saved in the field Returns: Resulting string if output_stream
is not specified. Else the number of bytes writtern.
-
_pfp__name
= None¶ The name of the Field
-
_pfp__parent
= None¶ The parent of the field
-
_pfp__parse
(stream, save_offset=False)[source]¶ Parse this field from the
stream
Stream: An IO stream that can be read from Save_offset: Save the offset into the stream Returns: None
-
_pfp__path
()[source]¶ Return the full pathname of this field. E.g. given the template below, the
a
field would have a full path ofroot.nested.a
struct { struct { char a; } nested; } root;
-
_pfp__set_value
(new_val)[source]¶ Set the new value if type checking is passes, potentially (TODO? reevaluate this) casting the value to something else
New_val: The new value Returns: TODO
-
_pfp__show
(level=0, include_offset=False)[source]¶ Return a representation of this field
Parameters: - level (int) – The indent level of the output
- include_offset (bool) – Include the parsed offsets of this field
-
_pfp__watch_fields
= []¶ All fields that this field is watching
-
_pfp__watchers
= []¶ All fields that are watching this field
-
-
class
pfp.fields.
Array
(width, field_cls, stream=None, metadata_processor=None)[source]¶ The array field
-
field_cls
= None¶ The class for items in the array
-
raw_data
= None¶ The raw data of the array. Note that this will only be set if the array’s items are a core type (E.g. Int, Char, etc)
-
width
= -1¶ The number of items of the array.
len(array_field)
also works
-
-
class
pfp.fields.
Struct
(stream=None, metadata_processor=None)[source]¶ The struct field
-
_pfp__add_child
(name, child, stream=None, overwrite=False)[source]¶ Add a child to the Struct field. If multiple consecutive fields are added with the same name, an implicit array will be created to store all fields of that name.
Parameters: - name (str) – The name of the child
- child (pfp.fields.Field) – The field to add
- overwrite (bool) – Overwrite existing fields (False)
- stream (pfp.bitwrap.BitwrappedStream) – unused, but her for compatability with Union._pfp__add_child
Returns: The resulting field added
-
_pfp__children
= []¶ All children of the struct, in order added
-
-
class
pfp.fields.
Array
(width, field_cls, stream=None, metadata_processor=None)[source] The array field
-
field_cls
= None The class for items in the array
-
implicit
= False¶ If the array is an implicit array or not
-
raw_data
= None The raw data of the array. Note that this will only be set if the array’s items are a core type (E.g. Int, Char, etc)
-
width
= -1 The number of items of the array.
len(array_field)
also works
-
-
class
pfp.fields.
BitfieldRW
(interp, cls)[source]¶ Handles reading and writing the total bits for the bitfield data type from the input stream, and correctly applying endian and bit direction settings.
-
read_bits
(stream, num_bits, padded, left_right, endian)[source]¶ Return
num_bits
bits, taking into account endianness and left-right bit directions
-
reserve_bits
(num_bits, stream)[source]¶ Used to “reserve”
num_bits
amount of bits in order to keep track of consecutive bitfields (or are the called bitfield groups?).E.g.
struct { char a:8, b:8; char c:4, d:4, e:8; }
Parameters: - num_bits (int) – The number of bits to claim
- stream (pfp.bitwrap.BitwrappedStream) – The stream to reserve bits on
Returns: If room existed for the reservation
-
-
class
pfp.fields.
Char
(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ A field representing a signed char
-
class
pfp.fields.
Double
(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ A field representing a double
-
class
pfp.fields.
Enum
(stream=None, enum_cls=None, enum_vals=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ The enum field class
-
class
pfp.fields.
Field
(stream=None, metadata_processor=None)[source] Core class for all fields used in the Pfp DOM.
All methods use the _pfp__XXX naming convention to avoid conflicting names used in templates, since struct fields will implement
__getattr__
and__setattr__
to directly access child fields
-
class
pfp.fields.
Float
(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ A field representing a float
-
class
pfp.fields.
Int
(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ A field representing a signed int
-
class
pfp.fields.
Int64
(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ A field representing a signed int64
-
class
pfp.fields.
IntBase
(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ The base class for all integers
-
class
pfp.fields.
NumberBase
(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ The base field for all numeric fields
-
class
pfp.fields.
Short
(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ A field representing a signed short
-
class
pfp.fields.
String
(stream=None, metadata_processor=None)[source]¶ A null-terminated string. String fields should be interchangeable with char arrays
-
class
pfp.fields.
Struct
(stream=None, metadata_processor=None)[source] The struct field
-
class
pfp.fields.
UChar
(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ A field representing an unsigned char
-
class
pfp.fields.
UInt
(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ A field representing an unsigned int
-
class
pfp.fields.
UInt64
(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ A field representing an unsigned int64
-
class
pfp.fields.
UShort
(stream=None, bitsize=None, metadata_processor=None, bitfield_rw=None, bitfield_padded=False, bitfield_left_right=False)[source]¶ A field representing an unsigned short
-
class
pfp.fields.
Union
(stream=None, metadata_processor=None)[source]¶ A union field, where each member is an alternate view of the data
-
class
pfp.fields.
Void
(stream=None, metadata_processor=None)[source]¶ The void field - used for return value of a function