Provided by: libdata-parsebinary-perl_0.31~dfsg-1_all 
NAME
Data::ParseBinary - Yet Another parser for binary structures
SYNOPSIS
$s =
Struct("Construct",
Struct("Header",
Magic("MZ"),
Byte("Version"),
UBInt32("Expire Date"),
Enum(UBInt32("Data Type"),
Array => 0,
String => 1,
Various => 2,
),
Byte("Have Extended Header"),
If ( sub { $_->ctx->{"Have Extended Header"} },
CString("Author")
),
),
Switch("data", sub { $_->ctx->{Header}->{"Data Type"} },
{
Array => Array(4, SBInt32("Signed Int 32")),
String => PascalString("Name"),
Various =>
Struct("Various data",
NoneOf(Byte("value"), [4, 9]),
Padding(1), # byte
BitStruct("Mini Values",
Flag("done"),
Nibble("Short"),
Padding(1), #bit
SBInt16("something"),
),
),
}
),
);
my $data = $s->parse("MZabcde\0\0\0\1\1semuel\0\x05fghij");
# $data contains:
# {
# 'Header' =>
# {
# 'Version' => 97,
# 'Expire Date' => 1650680933
# 'Data Type' => 'String',
# 'Have Extended Header' => 1,
# 'Author' => 'semuel',
# }
# 'data' => 'fghij',
# }
DESCRIPTION
This module is a Perl Port for PyConstructs http://construct.wikispaces.com/
This module enables writing declarations for simple and complex binary structures, parsing
binary to hash/array data structure, and building binary data from hash/array data
structure.
Reference Code
Struct
$s = Struct("foo",
UBInt8("a"),
UBInt16("b"),
Struct("bar",
UBInt8("a"),
UBInt16("b"),
)
);
$data = $s->parse("ABBabb");
# $data is { a => 65, b => 16962, bar => { a => 97, b => 25186 } }
This is the main building block of the module - the struct. Whenever there is the need to
bind a few varibles together, use Struct. Many constructs receive only one sub-construct
as parameter, (for example, all the conditional constructs) so use Struct.
Primitives
Byte-Primitives
But this Struct is just an empy shell. we need to fill it with data types. So here is a
list of primitive elements:
Byte, UBInt8, ULInt8 (All three are aliases to the same things)
SBInt8, SLInt8
UBInt16
ULInt16
SBInt16
SLInt16
UBInt32
ULInt32
SBInt32
SLInt32
BFloat32
LFloat32
UBInt64
ULInt64
SBInt64
SLInt64
BFloat64
LFloat64
S - Signed, U - Unsigned, L - Little endian, B - Big Endian Samples:
UBInt16("foo")->parse("\x01\x02") == 258
ULInt16("foo")->parse("\x01\x02") == 513
UBInt16("foo")->build(31337) eq 'zi'
SBInt16("foo")->build(-31337) eq "\x85\x97"
SLInt16("foo")->build(-31337) eq "\x97\x85"
And of course, see Struct above to how bundle a few primitives together.
Be aware that the Float data type is not portable between platforms. So it is advisable
not to use it when there is an alternative.
Bit-Primitives
Flag, Bit (1 bit)
Nibble (4 bits)
Octet (8 bits, equal to "Byte")
BitField (variable length)
These primitive are bit-wide. however, unless using BitStruct, they take a whole byte from
the input stream. Take for example this struct:
$s = Struct("bits",
Flag("a"),
Nibble("b"),
);
$data = $s->parse("\x25\x27");
# data is { a => 1, b => 7 }
"\x25\x27" is 0010010100100111 in binary. The Flag is first, and it takes one byte from
the stream (00100101) use the last bit (1) and discard the rest. After it comes the
Mibble, that takes a byte too, (00100111) use the last four bits (0111) and discard the
rest.
If you need these bits to be packed tight together, see BitStruct.
Examples for the rest of the bit constructs:
$s = Struct("bits",
Octet("a"),
BitField("b", 5),
);
$data = $s->parse("\x25\x27");
# data is { a => 37, b => 7 }
Meta-Constructs
Life isn't always simple. If you only have a rigid structure with constance types, then
you can use other modules, that are far simplier. hack, use pack/unpack.
So if you have more complicate requirements, welcome to the meta-constructs. Basically,
you pass a code ref to the meta-construct, which will be used while parsing and building.
For every data that the code ref needs, the $_ variable is loaded with all the data that
you need. $_->ctx is equal to $_->ctx(0), that returns hash-ref containing all the data
that the current struct parsed. Is you want to go another level up, just request
$_->ctx(1).
Also avialble are $_->obj, when need to inspect the current object, (see RepeatUntil) and
$_->stream, which gives the current stream. (mostly used as $_->stream->tell to get the
current location)
As a rule, everywhere a code-ref is used, a simple number can be used too. If it doesn't
- it's a bug. please report it.
Meta-Primitives
Field (Bytes)
The first on is the field. a Field is a chunk of bytes, with variable length:
$s = Struct("foo",
Byte("length"),
Field("data", sub { $_->ctx->{length} }),
);
(it can be also in constent length, by replacing the code section with, for example, 4) So
we have struct, that the first byte is the length of the field, and after that the field
itself. An example:
$data = $s->parse("\x03ABC");
# $data is {length => 3, data => "ABC"}
$data = $s->parse("\x04ABCD");
# $data is {length => 4, data => "ABCD"}
And so on.
Field is also called Bytes.
Value
A calculated value - not in the stream. It is calculated on both parse and build.
$s = Struct("foo",
UBInt8("width"),
UBInt8("height"),
Value("total_pixels", sub { $_->ctx->{width} * $_->ctx->{height}}),
);
Alias
Copies "a" to "b".
$s = Struct("foo",
Byte("a"),
Alias("b", "a"),
);
$data = $s->parse("\x25");
# $data is { a => 37, b => 37 }
Conditionals
If / IfThenElse
Basic branching:
$s = Struct("foo",
Flag("has_options"),
If(sub { $_->ctx->{has_options} },
Bytes("options", 5)
)
);
The If statment takes it's name from the contained construct, and return undef of the
condition is not met.
$s = Struct("foo",
Flag("long_options"),
IfThenElse("options", sub { $_->ctx->{long_options} },
Bytes("Long Options", 5),
Bytes("Short Options", 3),
),
);
The IfThenElse discard the name of the contained consturct, and use its own.
Switch
Multi branching. Can operate on numbers or strings. In the first example used with Enum to
convert a value to string.
The Switch discard the name of the contained consturcts, and use its own. return undef if
$DefaultPass is used.
$s = Struct("foo",
Enum(Byte("type"),
INT1 => 1,
INT2 => 2,
INT4 => 3,
STRING => 4,
),
Switch("data", sub { $_->ctx->{type} },
{
INT1 => UBInt8("spam"),
INT2 => UBInt16("spam"),
INT4 => UBInt32("spam"),
STRING => String("spam", 6),
}
)
);
$data = $s->parse("\x01\x12");
# $data is {type => "INT1", data => 18}
$data = $s->parse("\x02\x12\x34");
# $data is {type => "INT2", data => 4660}
$data = $s->parse("\x04abcdef");
# $data is {type => "STRING", data => 'abcdef'}
And so on. Switch also have a default option:
$s = Struct("foo",
Byte("type"),
Switch("data", sub { $_->ctx->{type} },
{
1 => UBInt8("spam"),
2 => UBInt16("spam"),
},
default => UBInt8("spam")
)
);
And can use $DefaultPass that make it to no-op.
$s = Struct("foo",
Byte("type"),
Switch("data", sub { $_->ctx->{type} },
{
1 => UBInt8("spam"),
2 => UBInt16("spam"),
},
default => $DefaultPass,
)
);
$data = $s->parse("\x01\x27");
# $data is { type => 1, data => 37 }
$DefaultPass is valid also as one of the options:
$s = Struct("foo",
Byte("type"),
Switch("data", sub { $_->ctx->{type} },
{
1 => $DefaultPass,
2 => UBInt16("spam"),
},
default => UBInt8("spam"),
)
);
$data = $s->parse("\x01\x27");
# $data is { type => 1, data => undef }
Loops
Array
Array, as any meta construct, and have constant length or variable lenght.
# This is an Array of four bytes
$s = Array(4, UBInt8("foo"));
$data = $s->parse("\x01\x02\x03\x04");
# $data is [1, 2, 3, 4]
# Array with variable length
$s = Struct("foo",
Byte("length"),
Array(sub { $_->ctx->{length}}, UBInt16("data")),
);
$data = $s->parse("\x03\x00\x01\x00\x02\x00\x03");
# $data is {length => 3, data => [1, 2, 3]}
RepeatUntil
RepeatUntil gets for every round to inspect data on $_->obj:
$s = RepeatUntil(sub {$_->obj eq "\x00"}, Field("data", 1));
$data = $s->parse("abcdef\x00this is another string");
# $data is [qw{a b c d e f}, "\0"]
Adapters
Adapters are constructs that transform the data that they work on. It wraps some
underlining structure, and present the data in a new, easier to use, way. There are some
built-in adapters for general use, but it is easy to write one of your own.
This is actually the easiest way to extend the framework. For creating an adapter, the
class should inherent from the Data::ParseBinary::Adapter class. For example, we will take
the IP address. An IP address can be viewed as four bytes, or one unsigned long integer,
but humans like to see it as dotted numbers. ("1.2.3.4") Here is how I would have done
it. First, I'll write an adapter class:
package IpAddressAdapter;
our @ISA = qw{Data::ParseBinary::Adapter};
sub _encode {
my ($self, $tvalue) = @_;
return [split '\.', $tvalue];
}
sub _decode {
my ($self, $value) = @_;
return join '.', @$value;
}
This adapter transforms dotted IP address ("1.2.3.4") to four numbers. Each number size is
"byte", so we will use an array of four bytes. For actually creating one we should write:
my $ipAdapter = IpAddressAdapter->create(Array(4, Byte("foo")));
(An adapter inherits its name from the underlying data construct)
Or we can create a little function:
sub IpAddressAdapterFunc {
my $name = shift;
IpAddressAdapter->create(Array(4, Byte($name)));
}
And then:
IpAddressAdapterFunc("foo")->parse("\x01\x02\x03\x04");
# will return "1.2.3.4"
On additional note, it is possible to declare an "init" sub inside IpAddressAdapter, that
will receive any extra parameter that "create" recieved.
Enum
One of the built-in Adapters is Enum:
$s = Enum(Byte("protocol"),
TCP => 6,
UDP => 17,
);
$s->parse("\x06") # return 'TCP'
$s->parse("\x11") # return 'UDP'
$s->build("TCP") # returns "\x06"
It is also possible to have a default:
$s = Enum(Byte("protocol"),
TCP => 6,
UDP => 17,
_default_ => blah => 99,
);
$s->parse("\x12") # returns 'blah'
Please note that the default tag must not be one of the supplied pairs. And finally:
$s = Enum(Byte("protocol"),
TCP => 6,
UDP => 17,
_default_ => $DefaultPass,
);
$s->parse("\x12") # returns 18
$DefaultPass tells Enum that if it isn't familiar with the value, pass it alone.
FlagsEnum
If the field represent a set of flags, then the library provide a construct just for that:
$s = FlagsEnum(ULInt16("characteristics"),
RELOCS_STRIPPED => 0x0001,
EXECUTABLE_IMAGE => 0x0002,
LINE_NUMS_STRIPPED => 0x0004,
REMOVABLE_RUN_FROM_SWAP => 0x0400,
BIG_ENDIAN_MACHINE => 0x8000,
);
$data = $s->parse("\2\4");
# $data is { EXECUTABLE_IMAGE => 1, REMOVABLE_RUN_FROM_SWAP => 1 };
Of course, this is equvalent to creating a BitStruct, and specifing Flag-s in the correct
positions, and so on. but this is an easier way.
Validators
Validator... validate. they validate that the value on the stream is an expected one, and
they validate that the value that need to be written to the stream is a correct one.
otherwise, throws an exception.
OneOf / NoneOf
OneOf(UBInt8("foo"), [4,5,6,7])->parse("\x05") # return 5
OneOf(UBInt8("foo"), [4,5,6,7])->parse("\x08") # dies.
NoneOf(UBInt8("foo"), [4,5,6,7])->parse("\x08") # returns 8
NoneOf(UBInt8("foo"), [4,5,6,7])->parse("\x05") # dies
Const
$s = Const(Bytes("magic", 6), "FOOBAR");
On parsing: verify that the correct value is being read, and return it.
On building: if value is supplied, verify that it is the correct one. if the value is not
supplied, insert the correct one.
Magic
Magic("\x89PNG\r\n\x1a\n")
A constant string that is written / read and verified to / from the stream. For example,
every PNG file starts with eight pre-defined bytes. this construct handle them,
transparant to the calling program. (you don't need to supply a value, nor you will see
the parsed value)
BitStruct
As said in the section about Bit-Primitives, these primitives are not packed tightly, and
each will take complete bytes from the stream. If you need to pack them tightly, use
BitStruct:
$s = BitStruct("foo",
BitField("a", 3), # three bit int
Flag("b"), # one bit
Nibble("c"), # four bit int
BitField("d", 5), # five bit int
);
$data = $s->parse("\xe1\xf2");
# $data is { a => 7, b => 0, c => 1, d => 30 }
As can be seen, we start with 1110000111110010. The it is being splitted as a=111, b=0,
c=0001, d=11110 and the rest (010) is discard.
BitStruct can be inside other BitStruct. Inside BitStruct, Struct and BitStruct are
equivalents.
$s = BitStruct("foo",
BitField("a", 3),
Flag("b"),
Nibble("c"),
Struct("bar",
Nibble("d"),
Bit("e"),
Octet("f"),
)
);
$data = $s->parse("\xe1\xf2\x34");
# $data is { a => 7, b => 0, c => 1, bar => { d => 15, e => 0, f => 70 } }
It is possible to mix a byte-primitives inside a BitStruct:
$s = BitStruct("foo",
BitField("a", 3),
UBInt16("int data"),
Nibble("b"),
);
$data = $s->parse("\xe1\xf2\x34");
# $data is { a => 7, "int data" => 3985, b => 10 }
Just be aware that this UBInt16 starts from the middle of the first byte, and ends in the
middle of the third.
BitStruct is based on a BitStream (see Stream) that is not seekable. So it can't contain
any construct that require seekability.
Bitwise
Use Bitwise when you are not under a BitStream, and you have single construct that need to
be packed by bits, and you don't want to create another hash for just this construct. Here
is an example from BMP:
Bitwise(Array(sub { $_->ctx(2)->{width} }, Nibble("index")));
We have an array of Nibble, that need to be packed together.
ReversedBitStruct and ReversedBitField
BitStruct assumes that each byte is arranged, bit-wise, from the most significante bit
(MSB) to the least significante bit. (LSB) However, it is not always true.
Lets say that you bytes are:
MSB LSB
Byte 1: A B C D E F G H
Byte 2: I J K M L N O P
And suppose that you have a bit-struct with three fields. AF1 is three bits, AF2 is one
bit, and AF3 is eight bits. so if:
AF1=ABC, AF2=D, AF3=EFGHIJKM
use: BitStruct with BitField
AF1=CBA, AF2=D, AF3=MKJIHGFE
use: BitStruct with ReversedBitField
AF1=HGF, AF2=E, AF3=DCBAPONL
use: ReversedBitStruct with BitField
AF1=FGH, AF2=E, AF3=LNOPABCD
use: ReversedBitStruct with ReversedBitField
Padding
Padding remove bytes from the stream
$s = Struct("foo",
Padding(2),
Flag("myflag"),
Padding(5),
);
$data = $s->parse("\x00\x00\x01\x00\x00\x00\x00\x00");
# $data is { myflag => 1 }
However, if woring on Bit Stream, then Padding takes bits and not bytes
$s = BitStruct("foo",
Padding(2),
Flag("myflag"),
Padding(5),
);
$data = $s->parse("\x20");
# $data is { myflag => 1 }
Padding is a meta-construct, can take code ref instead of a number
$s = Struct("foo",
Byte("count"),
Padding( sub { $_->ctx->{count} } ),
Flag("myflag"),
);
$data = $s->parse("\x02\0\0\1");
# $data is { count => 2, muflag => 1 }
Peeking and Jumping
Not all parsing is linear. sometimes you need to peek ahead to see if a certain value
exists ahead, or maybe you know where the data is, it's just that it is some arbitary
number of bytes ahead. or before.
Pointer and Anchor
Pointers are another animal of meta-struct. For example:
$s = Struct("foo",
Pointer(sub { 4 }, Byte("data1")), # <-- data1 is at (absolute) position 4
Pointer(sub { 7 }, Byte("data2")), # <-- data2 is at (absolute) position 7
);
$data = $s->parse("\x00\x00\x00\x00\x01\x00\x00\x02");
# $data is {data1=> 1 data2=>2 }
Literaly is says: jump to position 4, read byte, return to the beginning, jump to position
7, read byte, return to the beginning.
Anchor can help a Pointer to find it's target:
$s = Struct("foo",
Byte("padding_length"),
Padding(sub { $_->ctx->{padding_length} } ),
Byte("relative_offset"),
Anchor("absolute_position"),
Pointer(sub { $_->ctx->{absolute_position} + $_->ctx->{relative_offset} }, Byte("data")),
);
$data = $s->parse("\x05\x00\x00\x00\x00\x00\x03\x00\x00\x00\xff");
# $data is { absolute_position=> 7, relative_offset => 3, data => 255, padding_length => 5 }
Anchor saves the current location in the stream, enable the Pointer to jump to location
relative to it.
Also, $_->stream->tell will point you to the current location, giving the ability for
relative location without using Anchor. The above construct is quevalent to:
$s = Struct("foo",
Byte("padding_length"),
Padding(sub { $_->ctx->{padding_length} } ),
Byte("relative_offset"),
Pointer(sub { $_->stream->tell + $_->ctx->{relative_offset} }, Byte("data")),
);
Peek
$s = Struct("foo",
Byte("a"),
Peek(Byte("b")),
Byte("c"),
);
Peek is like Pointer with two differences: one that it is no-op on build. second the
location is calculated relative to the current location, while with Pointer it's absolute
position.
If no distance is supplied, zero is assumed. it is posible to supply constant distance,
(i.e. 5) or code ref. Examples:
Peek(UBInt16("b"), 5) # Peek 5 bytes ahead
Peek(UBInt16("b"), sub { $_->ctx->{this_far} }) # calculated number of bytes ahead
Strings
Char
The Char construct represent a single character. This can mean one byte, or if it have
encoding attached, a multi-byte character.
$s = Char("c", "utf8");
$s->build("\x{1abcd}");
# returns "\xf0\x9a\xaf\x8d"
The allowded encodings are:
UTF-32LE
UTF-32BE
UTF-16LE
UTF-16BE
UTF-8
utf8
or any single-byte encoding supported by the Encode module
for example: iso-8859-8
If you don't know if your unicode string is BE or LE, then it's probably BE.
String (constant length / meta)
A string with constant length:
String("foo", 5)->parse("hello")
# returns "hello"
A string with variable length, and encoding:
String("description", sub { $_->ctx->{description_size} }, encoding => 'UTF-16LE' )
The string length is specified in *characters*, not bytes.
PaddedString
A Padded string with constant length:
$s = PaddedString("foo", 10, padchar => "X", paddir => "right");
$s->parse("helloXXXXX") # return "hello"
$s->build("hello") # return 'helloXXXXX'
I think that it speaks for itself. only that paddir can be one of qw{right left center},
and there can be also trimdir that can be "right" or "left".
When encoding is supplied, for example:
$s = PaddedString("foo", 10, encoding => "utf8");
The String length is still specified in *bytes*, not characters. If anyone ever encouter a
padded constant length string with multi byte encoding that it's length is specified in
characters, please send me an email.
PascalString
PascalString - String with a length marker in the beginning:
$s = PascalString("foo");
$s->build("hello world") # returns "\x0bhello world"
The marker can be of any kind:
$s = PascalString("foo", \&UBInt16);
$s->build("hello") # returns "\x00\x05hello"
(the marker can be pointer to any function that get a name and return construct. And on
parse that construct should return a value. like the built-in primitives for example)
With encoding:
$s = PascalString("foo", undef, "utf8");
The string length is specified in *characters*, not bytes.
CString
And finally, CString:
$s = CString("foo");
$s->parse("hello\x00") # returns 'hello'
Can have many optional terminators:
$s = CString("foo", terminators => "XYZ");
$s->parse("helloY") # returns 'hello'
With encoding:
$s = CString("foo", encoding => "utf8");
Union / RoughUnion
$s = Union("foo",
UBInt32("a"),
UBInt16("b")
);
$data = $s->parse("\xaa\xbb\xcc\xdd");
# $data is { a => 2864434397, b => 43707 }
A Union. currently work only with constant-size constructs, (like primitives, Struct and
such) but not on bit-stream.
$s = Struct("records",
ULInt32("record_size"),
RoughUnion("params",
Field("raw", sub { $_->ctx(1)->{record_size} - 8 }),
Array(sub { int(($_->ctx(1)->{record_size} - 8) / 4) }, ULInt32("params")),
),
);
RoughUnion is a type of Union, that doesn't check the size of it's sub-constructs. it is
used when we don't know before-hand the size of the sub-constructs, and the size of the
union as a whole. In the above example, we assume that if the union target is the array of
integers, then it probably record_size % 4 = 0.
If it's not, and we build this construct from the array, then we will be a few bytes
short.
Aligned
$s = Struct("bmp",
ULInt32("width"),
ULInt32("height"),
Array(
sub { $_->ctx->{height} },
Aligned(
Array(
sub { $_->ctx(2)->{width} },
Byte("index")
),
4),
),
);
Aligned make sure that the contained construct's size if dividable by $modulo. the syntex
is:
Aligned($subcon, $modulo);
In the above example, we have an excert from the BMP parser. each pixel is a byte. There
is an array of lines (height) that each line is an array of pixels. each line is aligned
to a four bytes boundary.
The modulo can be any number. 2, 4, 8, 7, 23.
Terminator
Terminator()->parse("")
verify that we reached the end of the stream. Not very useful, unless you are processing a
file and need to verify that you have reached the end
LasyBound
This construct is estinental for recoursive constructs.
$s = Struct("foo",
Flag("has_next"),
If(sub { $_->ctx->{has_next} }, LazyBound("next", sub { $s })),
);
$data = $s->parse("\x01\x01\x01\x00");
# $data is:
# {
# has_next => 1,
# next => {
# has_next => 1,
# next => {
# has_next => 1,
# next => {
# has_next => 0,
# next => undef
# }
# }
# }
# }
Sequence
Similar to Struct, just return an arrat reference instead of hash ref
$s = Sequence("foo",
UBInt8("a"),
UBInt16("b"),
Sequence("bar",
UBInt8("a"),
UBInt16("b"),
)
);
$data = $s->parse("ABBabb");
# $data is [ 65, 16962, [ 97, 25186 ] ]
Be aware that not every construct works well under Sequence. For example, Value will have
problems on building. Using Struct is prefered.
Depricated Constructs
A few construct are being depricated - for the reason that while parsing a binary stream,
you should know before-hand what are you going to get. If needed, it is possible to use
Peek or Pointer to look ahead.
These will be exported only by request, or by using the :all tag
use Data::ParseBinary qw{:all};
use Data::ParseBinary qw{UNInt64 OptionalGreedyRange};
Primitives
The following primitives are depricated, because I don't think it's good practice to
declare a structure with native-order byte order. What if someone will run your program
in a machine with the oposite byte order?
N stand for Platform natural
UNInt8
SNInt8
UNInt16
SNInt16
UNInt32
SNInt32
UNInt64
SNInt64
NFloat32
NFloat64
These will be exported only by request, or by using the :NATURALS tag
use Data::ParseBinary qw{:NATURALS};
Ranges
Please use Array, with constant or dynamic number of elements
# This is an array for 3 to 7 bytes
$s = Range(3, 7, UBInt8("foo"));
$data = $s->parse("\x01\x02\x03");
$data = $s->parse("\x01\x02\x03\x04\x05\x06\x07\x08\x09");
# in the last example, will take only 7 bytes from the stream
# A range with at least one byte, unlimited
$s = GreedyRange(UBInt8("foo"));
# A range with zero to unlimited bytes
$s = OptionalGreedyRange(UBInt8("foo"));
Optional
Optional construct may or may not be in the stream. Of course, it need a seekable stream.
The optional section usually have a Const in them, that indicates is this section exists.
my $wmf_file = Struct("wmf_file",
Optional(
Struct("placeable_header",
Const(ULInt32("key"), 0x9AC6CDD7),
ULInt16("handle"),
),
),
ULInt16("version"),
ULInt32("size"), # file size is in words
);
A better way is to Peek ahead, and decide if this part exists:
my $wmf_file = Struct("wmf_file",
Peek(ULInt32("header_key")),
If(sub { $_->ctx->{header_key} == 0x9AC6CDD7 },
Struct("placeable_header",
Const(ULInt32("key"), 0x9AC6CDD7),
ULInt16("handle"),
),
),
ULInt16("version"),
ULInt32("size"), # file size is in words
);
Streams
Until now, everything worked in single-action. build built one construct, and parse parsed
one construct from one string. But suppose the string have more then one construct in it?
Suppose we want to write two constructs into one string? (and if these constructs are in
bit-mode, we can't create and just join them)
So, anyway, we have streams. A stream is an object that let a construct read and parse
bytes from, or build and write bytes to.
Please note, that some constructs can only work on seekable streams.
String
is seekable, not bit-stream
This is the most basic stream.
$data = $s->parse("aabb");
# is equivalent to:
$stream = CreateStreamReader("aabb");
$data = $s->parse($stream);
# also equivalent to:
$stream = CreateStreamReader(String => "aabb");
$data = $s->parse($stream);
Being that String is the default stream type, it is not needed to specify it. So, if
there is a string contains two or more structs, that the following code is possible:
$stream = CreateStreamReader(String => $my_string);
$data1 = $s1->parse($stream);
$data2 = $s2->parse($stream);
The other way is equally possible:
$stream = CreateStreamWriter(String => undef);
$s1->build($data1);
$s2->build($data2);
$my_string = $stream->Flush();
The Flush command in Writer Stream says: finish doing whatever you do, and return your
internal object. For string writer it is simply return the string that it built. Wrapping
streams (like Bit, StringBuffer) finish whatever they are doing, flush the data to the
internal stream, and call Flush on that internal stream.
The special case here is Wrap, that does not call Flush on the internal stream. usefull
for some configurations. a Flush operation happens in the end of every build operation
automatically, and when a stream being destroyed.
In creation, the following lines are equvalent:
$stream = CreateStreamWriter(undef);
$stream = CreateStreamWriter('');
$stream = CreateStreamWriter(String => undef);
$stream = CreateStreamWriter(String => '');
Of course, it is possible to create String Stream with inital string to append to:
$stream = CreateStreamWriter(String => "aabb");
And any sequencal build operation will append to the "aabb" string.
StringRef
is seekable, not bit-stream
Mainly for cases when the string is to big to play around with. Writer:
my $string = '';
$stream = CreateStreamWriter(StringRef => \$string);
... do build operations ...
# and now the data in $string.
# or refer to: ${ $stream->Flush() }
Because Flush returns what's inside the stream - in this case a reference to a string.
For Reader:
my $string = 'MBs of data...';
$stream = CreateStreamReader(StringRef => \$string);
... parse operations ...
Bit
not seekable, is bit-stream
While every stream support bit-fields, when requesting 2 bits in non-bit-streams you get
these two bits, but a whole byte is consumed from the stream. In bit stream, only two bits
are consumed.
When you use BitStruct construct, it actually wraps the current stream with a bit stream.
If the stream is already bit-stream, it continues as usual.
What does it all have to do with you? great question. Support you have a string containing
a few bit structs, and each struct is aligned to a byte border. Then you can use the
example under the BitStruct section.
However, if the bit structs are not aligned, but compressed one against the other, then
you should use:
$s = BitStruct("foo",
Padding(1),
Flag("myflag"),
Padding(3),
);
$inner = "\x42\0";
$stream1 = CreateStreamReader(Bit => String => $inner);
$data1 = $s->parse($stream1);
# data1 is { myflag => 1 }
$data2 = $s->parse($stream1);
# data2 is { myflag => 1 }
$data3 = $s->parse($stream1);
# data3 is { myflag => 0 }
Note that the Padding constructs detects that it work on bit stream, and pad in bits
instead of bytes.
On Flush the bit stream write the reminding bits (up to a byte border) as 0, write the
last byte to the contained stream, and call Flush on the said contained stream. so, if we
use the $s from the previous code section:
$stream1 = CreateStreamWriter(Bit => String => undef);
$s->build({ myflag => 1 }, $stream1);
$s->build({ myflag => 1 }, $stream1);
$s->build({ myflag => 0 }, $stream1);
my $result = $stream1->Flush();
# $result eq "\x40\x40\0"
In this case each build operation did Flush on the bit stream, closing the last (and only)
byte. so we get three bytes, each contain one record. But if we want that our constructs
will be compressed each against the other, then we need to protect the bit stream from the
Flush command:
$stream1 = CreateStreamWriter(Wrap => Bit => String => undef);
$s->build($data1, $stream1);
$s->build($data1, $stream1);
$s->build($data2, $stream1);
my $result = $stream1->Flush()->Flush();
# $result eq "\x42\0";
Ohh. Two Flushs. one for the Wrap, one for the Bit and the String. However, as you can
see, the structs are packed together. The Wrap stream protects the Bit stream from the
Flush command in the end of every build.
StringBuffer
is seekable, not bit-stream
Suppose that you have some non-seekable stream. like socket. and suppose that your struct
do use construct that need seekable stream. What can you do?
Enter StringBuffer. It reads from the warped stream exactly the number of bytes that the
struct needs, giving the struct the option to seek inside the read section. and if the
struct seeks ahead - it will just read enough bytes to seek to this place.
In writer stream, the StringBuffer will pospone writing the data to the actual stream,
until the Flush command.
This warper stream is usefull only when the struct seek inside it's borders, and not
sporadically reads data from 30 bytes ahead / back.
# suppose we have unseekable reader stream names $s_stream
# (for example, TCP connection)
$stream1 = CreateStreamReader(StringBuffer => $s_stream);
# $s is some struct that uses seek. (using Peek, for example)
$data = $s->parse($stream1);
# the data were read, you can either drop $stream1 or continue use
# it for future parses.
# now suppose we have a unseekable writer strea name $w_stream
$stream1 = CreateStreamWriter(StringBuffer => $w_stream);
# $s is some struct that uses seek. (using Peek, for example)
$s->build($data1, $stream1);
# data is written into $stream1, flushed to $w_stream, and sent.
Note that in StringBuffer, the Flush operation writes the data to the underlining stream,
and then Flushes that stream.
Wrap
A simple wraping stream, whose only function is to protect the contained stream from Flush
commands. Usable only for writer streams, and can be used to:
1. Protect a Bit stream, so it will compress multiple structs without byte alignment (see
the Bit stream documentation for example)
2. Protect a StringBuffer, so it will aggregate some structs before you will Flush them
all as one to the socket/file/whatever.
File
is seekable, not bit-stream
Reads from / Writes to a file. it is your responsebility to open the file and binmode it.
open my $fh, "<", "bin_data.xdf" or die "oh sh...";
binmode $fh;
$stream1 = CreateStreamReader(File => $fh);
Format Library
The Data::ParseBinary arrive with ever-expanding set of pre-defined parsers for popular
formats. Each of these parsers is in it's own module. And if you have a file-format,
then this is how it's done:
use Data::ParseBinary::Graphics::BMP qw{$bmp_parser};
open my $fh2, "<", $filename or die "can not open $filename";
binmode $fh2;
$data = $bmp_parser->parse(CreateStreamReader(File => $fh2));
And $data will contain the parsed file. In the same way, it is possible to build a BMP
file.
Please look for the documentation inside each module, as it highlights various issues with
the various libraries.
Debugging
Output on failure
The first line of defence is the output on error. Where did it happend? in which
construct? In which byte of the input?
On error, you get the following "die" messege:
Got Exception not enought bytes in stream
Streams location:
1: Stream BitReader in byte #Bit 5
2: Stream StringReader in byte #2
Constructs Stack:
1: BitField f
2: Struct bar
3: BitStruct foo
It tells me that I was inside "f" under "bar" under "foo", that it's the second byte in
stream, and because I was inside a BitStuct I get another line for the stream, pointing me
to the exact bit.
$print_debug_info
What we miss in the "die" messege above, is knowing how did I got there. If it's inside
Array, how many times it happen, and what decissions taken along the way. But fear not.
just set $print_debug_info:
$Data::ParseBinary::print_debug_info = 1;
This will trigger a print every time the parsing process enter or exit a construct. So if
a parsing dies, you can follow where it did.
TODO
The following elements were not implemented:
OnDemand
Reconfig and a macro Rename
AlignedStruct
Probe
Embed
Tunnel (TunnelAdapter is already implemented)
Add documentation to: ExtractingAdapter
Move the insertion of the parsed value to the context from the Struct/Sequence constructs
to each indevidual construct?
Streams: SocketStream
FileStreamWriter::Flush : improve.
Ability to give the CreateStreamReader/CreateStreamWriter function an ability to
reconginze socket / filehandle / pointer to string.
Union need to be extended to bit-structs?
use some nice exception system
Fix the Graphics-EMF library : Find out if the EMF file should work or not. it fails on
the statment: Const(ULInt32("signature"), 0x464D4520) And complain that it gets "0".
Make BitField a meta construct?
Thread Safety
This is a pure perl module. there should be not problems.
BUGS
Currently L/BFloat64 does not work if you don't have 64 bit numbers support compiled in
your Perl
SEE ALSO
Original PyConstructs homepage: http://construct.wikispaces.com/
AUTHOR
Fomberg Shmuel, <owner@semuel.co.il>
COPYRIGHT AND LICENSE
Copyright 2008 by Shmuel Fomberg.
This library is free software; you can redistribute it and/or modify it under the same
terms as Perl itself.