SPVM::Packer(3)

📦 version 0.990125, in alpine 3.24

💖 SPVM::Packer — Pack and Unpack Operations 💖

okay so bestie, welcome to SPVM::Packer — it's a class in SPVM that has methods for pack and unpack operations. That's the whole vibe. (This is a page from User Contributed Perl Documentation, fyi, so you know exactly which little corner of the perl universe you're standing in 🫶)

🌸 Description 🌸

The Packer class in SPVM has methods for pack and unpack operations. No cap. It takes your objects, smushes them into binary, and can pull them right back out again. Iconic behaviour, honestly.

✨ Usage ✨

here's the whole thing in action, literally:

use Packer;

my $packer = Packer->new;

{
  my $objects = [(object)1, 2L, 0.5, [1, 2], "abc"];

  my $binary = $packer->pack("lqdl2a128", $objects);

  my $objects_unpack = $packer->unpack("lqdl2a128", $binary);
}

{
  my $objects = [(object)[1, 2, 3]];

  my $binary = $packer->pack("l*", $objects);

  my $objects_unpack = $packer->unpack("l*", $binary);
}

see how the template "lqdl2a128" goes in and comes back out the same way? that's the whole point, bestie 💅

👑 Class Methods 👑

💜 static method new : Packer ();

Creates a new Packer object. That's it. That's the method. Slay. ✨

🦋 Instance Methods 🦋

💖 pack

static method pack : string ($template : string, $objects : object[]);

Converts the objects $objects to a binary data according to the template $template, and returns it. so you hand it a pile of objects and a template, and it hands you back a string of raw bytes. main character energy fr.

🎀 Template Syntax 🎀

A template is a string. It consist of specifier parts.

TEMPLATE := "SpecifierPart1SpecifierPart2SpecifierPartN"

A specifier part is consist of a speficier, an endian, and a length. An endian and a length are optional.

SpecifierPart := Specifier[Endian][Length]

Here is the list of specifiers. (yes, they're giving very much a la carte menu 🍓)

  • a — string → string. It is null padded in pack method.
  • h — string → A hex string (low nybble first)
  • H — string → A hex string (high nybble first)
  • c — Byte or byte[] → Signed 8-bit integers
  • C — Byte or byte[] → Unsigned 8-bit integers
  • s — Short or short[] → Signed 16-bit integers
  • S — Short or short[] → Unsigned 16-bit integers
  • l — Int or int[] → Signed 32-bit integers
  • L — Int or int[] → Unsigned 32-bit integers
  • q — Long or long[] → Signed 64-bit integers
  • Q — Long or long[] → Unsigned 64-bit integers
  • f — Float or float[] → 32-bit floating point numbers.
  • d — Double or double[] → 64-bit floating point numbers.

(yes, the left column is the specifier, the middle is the Types, and the right one is an output binary in pack or an input binary in unpack 👑)

An endian is big-endian > or little-endian >. (that's exactly how the doc spells it, bestie — two >s, don't come for me 🙈)

  • If big-endian is specified, the binary data is converted from big-endian to system-endian in pack method, or from system-endian to big-endian in unpack method.
  • If little-endian is specified, the binary data is converted from little-endian to system-endian in pack method, or from system-endian to little-endian in unpack method.

A length must be a positive integer or a wildcard *. If a length or a wildcard is specified, the type (such as Int) becomes a corresponding array type (such as int[]). so like, l2 gives you int[] with two of them, and l* gives you the whole wildcard situation. okay that last bit was me explaining the vibe, the doc just says what it says 👑

💀 Exceptions 💀

okay so pack is a little dramatic. it will throw at you. here's the full list of ways to upset it:
  • If template syntax is invalid, an exception is thrown.
  • The template $template must be defined. Otherwise an exception is thrown.
  • The objects $objects must be defined. Otherwise an exception is thrown.
  • The length of the specifiers in the template $template must be less than or equal to the lenght of the objects $objects. Otherwise an exception is thrown.
  • The type of the element in the objects $objects is invalid, an exception is thrown.

💅 unpack

static method unpack : object[] ($template : string, $binary : string);

Converts the binary data $binary to the objects $objects according to the template $template, and returns it. so it's the reverse glow-up of pack — bytes go in, objects come out, everyone cheers 🌈

See "pack" method about templates. same menu, same rules, same everything.

💀 Exceptions 💀

once again, the drama. unpack has its own list:
  • If template syntax is invalid, an exception is thrown.
  • The template $template must be defined. Otherwise an exception is thrown.
  • The binary data $binary must be defined. Otherwise an exception is thrown.
  • The current offset $binary_offset plus (the size $size * the length $length of the specifier) must be less than the length($binary_length) of the binary data $binary. Otherwise an exception is thrown.

Copyright (c) 2024 Yuki Kimoto

MIT License

and that's the whole page, bestie 🎀 — brought to you by perl v5.42.2, dated 2026-02-03, filed under SPVM::Packer(3). go pack something iconic 💖✨

📦 where this page comes from