Data::ParseBinary(3pm) User Contributed Perl Documentation Data::ParseBinary(3pm)
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 11semuel 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("x01x02") == 258
ULInt16("foo")->parse("x01x02") == 513
UBInt16("foo")->build(31337) eq 'zi'
SBInt16("foo")->build(-31337) eq "x85x97"
SLInt16("foo")->build(-31337) eq "x97x85"
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("x25x27");
# data is { a => 1, b => 7 }
"x25x27" 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("x25x27");
# 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("x01x12");
# $data is {type => "INT1", data => 18}
$data = $s->parse("x02x12x34");
# $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("x01x27");
# $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("x01x27");
# $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("x01x02x03x04");
# $data is [1, 2, 3, 4]
# Array with variable length
$s = Struct("foo",
Byte("length"),
Array(sub { $_->ctx->{length}}, UBInt16("data")),
);
$data = $s->parse("x03x00x01x00x02x00x03");
# $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("abcdefx00this is another string");
# $data is [qw{a b c d e f}, "