Data::...eBinary(3pm)

📦
version 0.31 · 4 versions
, in debian bookworm, ubuntu jammy

👑 Data::ParseBinary(3pm) 👑

User Contributed Perl Documentation ✨ Data::ParseBinary(3pm)

okay bestie, grab a snack 🍓 because we are about to become unreasonably good at binary parsing

✨ NAME ✨

Data::ParseBinary — Yet Another parser for binary structures 🦋

🌈 SYNOPSIS 🌈

no cap, this is what it looks like when you're living your best life:

$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. literally the whole glow-up in one sentence 💅

🎀 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.

🫶 heads up bestie: 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 Nibble, that takes a byte too, (00100111) use the last four bits (0111) and discard the rest. so much ✨discarding✨

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). climbing the family tree fr fr 🌳

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. iconic behaviour honestly 💅

🔀 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. 💜

ok so this is literally the easiest way to extend the whole framework, bestie. 💖 For creating an adapter, your class should inherit from the Data::ParseBinary::Adapter class. For example, we'll 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's 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. no cap.

✅ 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 🧸

okay so a Padded string with constant length:

$s = PaddedString("foo", 10, padchar => "X", paddir => "right");
$s->parse("helloXXXXX") # return "hello"
$s->build("hello") # return 'helloXXXXX'

honestly bestie it kinda speaks for itself 💅 the only thing to know is that paddir can be one of qw{right left center}, and there's also trimdir which can be "right" or "left".

When encoding is supplied, like:

$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 — a 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. (yes it's the opposite of PaddedString, keep up bestie 🫶)

🎀 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 🌊

okay so 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. no cap.

String 🧵

is seekable, not bit-stream

This is the most basic stream. fr fr.

$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. iconic tbh.

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. 😭

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. slay.

📝 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. periodt.

💀 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 2008 by Shmuel Fomberg.

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

this page is from perl v5.32.0, dated 2021-01-04, and it's the Data::...eBinary(3pm) manual page. bye bestie, go parse something iconic 💖✨🦋

📦 where this page comes from