Parse:...Format(3pm)

💖 Parse::Binary::FixedFormat — the manual, but make it cute 💖

okay bestie, so this is Parse::Binary::FixedFormat, living in the User Contributed Perl Documentation section, manual page 3pm. Sit down, grab a strawberry, and let's get into it 🍓

---

✨ NAME ✨

Parse::Binary::FixedFormat — bestie, it converts between fixed-length fields and hashes. That's it. That's the whole vibe. 💅

---

🦋 SYNOPSIS 🦋

use Parse::Binary::FixedFormat;

my $tarhdr =
   new Parse::Binary::FixedFormat [ qw(name:a100 mode:a8 uid:a8 gid:a8 size:a12
                              mtime:a12 chksum:a8 typeflag:a1 linkname:a100
                              magic:a6 version:a2 uname:a32 gname:a32
                              devmajor:a8 devminor:a8 prefix:a155) ];
my $buf;
read TARFILE, $buf, 512;

# create a hash from the buffer read from the file
my $hdr = $tarhdr->unformat($buf);   # $hdr gets a hash ref

# create a flat record from a hash reference
my $buf = $tarhdr->format($hdr);     # $hdr is a hash ref

# create a hash for a new record
my $newrec = $tarhdr->blank();

look at her go. iconic behaviour, no notes 👑

---

🌸 DESCRIPTION 🌸

So Parse::Binary::FixedFormat is your girl for converting between a buffer that has fixed-length field definitions and a hash where every field has a name. It's giving bilingual — buffer on one side, hash on the other. 🫶

The perl pack and unpack functions are the ones actually doing the heavy lifting for the conversions. What Parse::Binary::FixedFormat does is build the format string by concatenating all the field descriptions together, and then translate between the lists that pack and unpack deal in and a hash that you can reference by field name. Lowkey genius, highkey useful. ✨

---

💅 METHODS 💅

Parse::Binary::FixedFormat provides the following methods. Let's go one by one, bestie.

🎀 new

To create a converter, invoke the new method with a reference to a list of field specifications.

my $cvt =
    new Parse::Binary::FixedFormat [ 'field-name:descriptor:count', ... ];

Field specifications contain the following information:

• field-name — this is the name of the field, and it's gonna be used as the hash index. That's her whole job. 💜
• descriptor — this describes the content and size of the field. All the descriptors get strung together and passed to pack and unpack as part of the template argument. Wanna know what you can put here? Run perldoc -f pack, bestie, that's the source of truth. 📖

Don't use repeat counts in the descriptor, except for the string types ("a", "A", "h, "H", and "Z"). And if you want to get an array out of the buffer, use the "count" argument instead. Noted, fr fr. 🙈

• count — this one specifies a repeat count for the field. If you give it a non-zero value, then this field's entry in the resulting hash will be an array reference instead of a scalar. Glow-up moment. 🔥

🦋 unformat

To convert a buffer of data into a hash, pass the buffer to the unformat method.

$hashref = $cvt->unformat($buf);

Parse::Binary::FixedFormat applies the constructed format to the buffer with "unpack" and maps the returned list of elements to hash entries. After that, fields are accessible by name through the hash:

print $hashref->{field-name};
print $hashref->{array-field}[3];

she's giving you everything, by name, on demand 💖

🌈 format

To convert the hash back into a fixed-format buffer, pass the hash reference to the format method.

$buf = $cvt->format($hashref);

round trip, bestie. we love a reversible relationship 💞

⭐ blank

To get a hash that can be used to create a new record, call the blank method.

$newrec = $cvt->blank();

fresh start, blank slate, main character energy ✨

---

👑 ATTRIBUTES 👑

Each Parse::Binary::FixedFormat instance contains the following attributes. Yes, she has lore.

• Names — Names contains a list of the field names for this variant. 📝
• Count — Count contains a list of occurrence counts. This is used to indicate which fields contain arrays. 🔢
• Format — Format contains the template string for the Perl pack and unpack functions. 🧵

---

🫶 AUTHORS 🫶

Audrey Tang <cpan@audreyt.org> — queen behaviour 💐

Based on Data::FixedFormat, written by Thomas Pfau <pfau@nbpfaus.net> http://nbpfaus.net/~pfau/. credit where credit is due, periodt 💜

---

📜 COPYRIGHT 📜

Copyright 2004-2009 by Audrey Tang <cpan@audreyt.org>.

Copyright (C) 2000,2002 Thomas Pfau. All rights reserved.

This module is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

ok so legally speaking: it's free, you can share it, but it comes with absolutely zero promises. read the GPL, bestie, it's the whole plot. 😭

---

and that's the page!! 💖 this lil doc is from perl v5.36.0, dated 2022-12-04, and it lives in Parse:...Format(3pm). mwah, go forth and pack/unpack responsibly 🎀✨🦋