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

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

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

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

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, 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

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

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

    $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

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

    $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

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

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

    $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

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

Primitives

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

    # 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

    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
    );

String

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

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

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

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

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

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);

Output on failure

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

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