pdf-raku / native-packing-raku

Struct packing/unpacking from binary data

Native-Packing-raku

Description

Native::Packing is a simple solution for structured reading and writing of binary numerical data.

Example

use v6;
use Native::Packing :Endian;

# open a GIF read the header
my class LogicalDescriptor
    does Native::Packing[Endian::Vax] {

    has uint16 $.width;
    has uint16 $.height;
    has uint8  $.flags;
    has uint8  $.bgColorIndex;
    has uint8  $.aspect;
}

my $fh = "t/lightbulb.gif".IO.open( :r, :bin);
my $offset = 6;  # skip GIF header

my LogicalDescriptor $screen .= read: $fh, :$offset;
say "GIF has size {$screen.width} X {$screen.height}";

It currently handles records containing native integers (int8, uint8, int16, etc), numerics (num32, num64) and sub-records of type Native::Packing.

• Data may read be and written to binary files, via the read and write methods

• Or read and written to buffers via the unpack and pack methods.

Endianess

The two fixed modes are:

• Vax (little endian) - least significant byte written first

• Network (big endian) - most significant byte written first

The endianess of the binary format needs to be known to correctly read and write to it.

There is also a platform-dependant Host mode. This will read and write binary data in the same endianess as the host computer.

Endian Examples:

use Native::Packing :Endian;
class C { has int16 $.a }
my $c = C.new: :a(42);
say ($c but Native::Packing[Vax]).pack;     # Buf[uint8]:0x<2a 00>
say ($c but Native::Packing[Network]).pack; # Buf[uint8]:0x<00 2a>
say ($c but Native::Packing[Host]).pack;    # Depends on your host

native-packing-raku's Issues

Wishlist: Allow native shaped arrays

Would like to allow native shaped arrays; possibly:

use Native::Packing :Endian;
class GifHeader does Native::Packing[Endian::Vax] {
    HAS byte @.gif-header[6];
    has uint16 $.width;
    has uint16 $.height;
}

The problem is introspecting the shape of the @.gif-header attribute. Have created an RT https://rt.perl.org/Ticket/Display.html?id=131174

Revamp, use native subs for performance.

Look for 'revamp' branch.

inheritance mishandled

A first attempt at basic inhertance:

use Test;
use Native::Packing :Endian;
plan 1;

class BaseStruct {
        has uint16 $.a;
        has uint8  $.b;
}

class Struct is BaseStruct does Native::Packing[Network] {
    has uint16 $.c;
}

my $s = Struct.new: :a(42), :b(99), :c(69);
my $n-buf = $s.pack;
is-deeply $n-buf.list, (
    0,42,
    99,
    0,69), 'network packing with inheritance';

done-testing;

The above test should pass if the storage a, b (from the base class) then c, but the test fails with:

1..1
not ok 1 - network packing with inheritance
# Failed test 'network packing with inheritance'
# at t/inheritance.t line 17
# expected: $(0, 42, 99, 0, 69)
#      got: $(0, 69, 0, 42, 99)
# You failed 1 test of 1

Which indicates we're currentl;y getting c, a, b.

"Little Endian" and "Big Endian" swapped in README.md

Hi! The current formulation in README.md is:

The two fixed modes are:

• Vax (big endian) - least significant byte written first
• Network (little endian) - most significant byte written first

The "big endian" and "little endian" strings are swapped, it should be:

The two fixed modes are:

• Vax (little endian) - least significant byte written first
• Network (big endian) - most significant byte written first