Badger::Codecs(3pm)

📦
version 0.16 · 4 versions
, in debian trixie, ubuntu noble, ubuntu resolute

🦋 Badger::Codecs 💖

okay bestie, pull up a chair, because this is Badger::Codecs(3pm) from the User Contributed Perl Documentation and it is lowkey the glow-up your data pipeline has been waiting for. this is part 1 of the page, so hydrate, stay with me, and let's get into it ✨

🌸 NAME 🌸

Badger::Codecs — modules for encoding and decoding data, fr fr. it's giving "codec manager" energy and it ate. 👑

✨ SYNOPSIS ✨

k so here's the vibe. first up: class methods, a single codec object, and honestly the basics that just work 💅

# using class methods
use Badger::Codecs;
$encoded = Badger::Codecs->encode( base64 => $original );
$decoded = Badger::Codecs->decode( base64 => $encoded );

# creating a single codec object
$codec   = Badger::Codecs->codec('base64');
$encoded = $codec->encode($original);
$decoded = $codec->decode($encoded);

then you can build a whole collection of codecs, with a base list and a codecs hash for the exceptions that don't get grokked automatically. iykyk 🫶

# creating a codecs collection
$codecs  = Badger::Codecs->new(
    base   => ['My::Codec', 'Badger::Codec'],
    codecs => {
        # most codec names are grokked automatigally from the
        # base defined above - this hash is for any exceptions
        wibble  => 'Ferret::Codec::Wibble',
        frusset => 'Stoat::Codec::Frusset',
    }
);

# encode/decode via codecs collective
$encoded = $codecs->encode( wibble => $original );
$decoded = $codecs->decode( wibble => $encoded );

# or via a specific codec
$codec   = $codecs->codec('wibble');
$encoded = $codec->encode($original);
$decoded = $codec->decode($encoded);

and THEN — and this is the part that made me gasp — you can import a codec straight into your namespace. no cap. 🎀

# importing a single codec
use Badger::Codecs
    codec => 'url';

# codec() returns a Badger::Codec::URL object
$encoded = codec->encode($text);
$decoded = codec->decode($encoded);

# encode() and decode() are imported subroutines
$encoded = encode($text);
$decoded = decode($encoded);

multiple codecs? yes bestie, we can do that too 💜

# import multiple codecs
use Badger::Codecs
    codecs => 'base64 storable';

# codec objects
base64->encode(...);    base64->decode(...);
storable->encode(...);  storable->decode(...);

# imported subroutines
encode_base64(...);     decode_base64(...);
encode_storable(...);   decode_storable(...);

codec chains, bestie. plural. stacked. iconic. 🔥

# import a codec chain
use Badger::Codecs
    codec => 'storable+base64';

# as before, now both codecs are applied
codec->encode(...);
codec->decode(...);
encode(...);
decode(...)

and you can name your codecs whatever you want with a hashref, so go off 👑

# multiple codecs with various options
use Badger::Codecs
    codecs => {
        link  => 'url+html',
        str64 => 'storable+base64',
    };

# codec objects
link->encode(...);      link->decode(...);
str64->encode(...);     str64->decode(...);

# subroutines
encode_link(...);       decode_link(...);
encode_str64(...);      decode_str64(...);

oh and you can pull all this through Badger::Class too, because of course you can 🌈

# accessing codecs via Badger::Class
use Badger::Class
    codec => 'base64';

codec();    encode(...);    decode(...);

use Badger::Class
    codecs => 'base64 storable';

base64();   encode_base64(...);    decode_base64(...);
storable(); encode_storable(...);  decode_storable(...);

💖 DESCRIPTION 💖

okay so like, what even is a codec? a codec is an object whose whole entire job is encoding and decoding data. main character energy, honestly. and this module right here implements a codec manager that locates, loads and instantiates those codec objects for you so you don't have to. it's the group chat admin of data conversion. periodt. 💅

🎀 Using Codecs 🎀

first thing's first: load the module, babe.

use Badger::Codecs;

you can do the classic OO thing — make a Badger::Codecs object, then call methods on it:

my $codecs  = Badger::Codecs->new();
my $codec   = $codecs->codec('url');
my $encoded = $codec->encode($original);
my $decoded = $codec->decode($encoded);

or you can just call class methods directly, no object needed, we're flexible ✨

my $codec   = Badger::Codecs->codec('url');
my $encoded = $codec->encode($original);
my $decoded = $codec->decode($encoded);

or, like, this way:

my $encoded = Badger::Codecs->encode(url => $original);
my $decoded = Badger::Codecs->decode(url => $encoded);

and bestie, all of those are literally the equivalent of doing it by hand:

use Badger::Codec::URL;
my $codec   = Badger::Codec::URL->new;
my $encoded = $codec->encode($original);
my $decoded = $codec->decode($encoded);

Badger::Codecs will do its absolute best to locate and load the right codec module for you. it defines a module base path — containing Badger::Codec and BadgerX::Codec by default — and then it appends the name of the codec you asked for in various forms until something sticks.

it first tries the name exactly as you specified it. if there's no codec module matching that, it tries a capitalised version of the name, and then an upper case version. so if you ask for a foo codec, you'll get back a Badger::Codec::foo, Badger::Codec::Foo, Badger::Codec::FOO — or an error gets thrown if none of them can be found. no crumbs left behind 🍓

NOTE: the above paragraph is incorrect. it now tries the capitalised version first to work around Apple's case-insensitive file system. this is subject to change. (we keep it real here, we don't edit the lore 💀)
my $codec = Badger::Codecs->code('url');
    # tries: Badger::Codec + url = Badger::Codec::url   # Nope
    # tries: Badger::Codec + Url = Badger::Codec::Url   # Nope
    # tries: Badger::Codec + URL = Badger::Codec::URL   # Yay!

🦋 Chained Codecs 🦋

okay this is my favourite part. codecs can be chained together in sequence. just write the names of the individual codecs separated by + characters. whitespace between the names and the + is optional — live your truth 🌸

the codec chain you get back (Badger::Codec::Chain) behaves exactly like any other codec. the only difference is that it applies several codecs in sequence. stacked. layered. stunning. 👑

my $codec = Badger::Codecs->codec('storable+base64');
$encoded = $codec->encode($data);       # encode storable then base64
$decoded = $codec->decode($encoded);    # decode base64 then storable

heads up though: the decoding process for a chain happens in reverse order, so that a round trip between encode() and decode() gives you back the original unencoded data. symmetry, bestie. it's giving balance 🧚

💜 Import Hooks 💜

the codec and codecs import hooks let you load and define codec subroutines into another module. it's literally so handy.

package My::Module;

use Badger::Codecs
    codec => 'base64';

the codec import hook defines a codec() subroutine that returns a reference to a codec object. it also defines encode() and decode() subroutines mapped to that codec. two for one, we love a deal 🫶

# using the codec reference
$encoded = codec->encode($original);
$decoded = codec->decode($encoded);

# using the encode/decode subs
$encoded = encode($original);
$decoded = decode($encoded);

the codecs import hook lets you define several codecs at once. a subroutine gets generated to reference each codec, along with the encoding and decoding subroutines. a whole little family 🌈

use Badger::Codecs
    codecs => 'base64 storable';

# codec objects
$encoded = base64->encode($original);
$decoded = base64->decode($encoded);
$encoded = storable->encode($original);
$decoded = storable->decode($encoded);

# imported subroutines
$encoded = encode_base64($original);
$decoded = decode_base64($encoded);
$encoded = encode_storable($original);
$decoded = decode_storable($encoded);

and you can define alternate names for codecs by handing it a reference to a hash array. name them whatever you want, bestie, it's your world 💅

use Badger::Codecs
    codecs => {
        text => 'base64',
        data => 'storable+base64',
    };

# codec objects
$encoded = text->encode($original);
$decoded = text->decode($encoded);
$encoded = data->encode($original);
$decoded = data->decode($encoded);

# imported subroutines
$encoded = encode_text($original);
$decoded = decode_text($encoded);
$encoded = encode_data($original);
$decoded = decode_data($encoded);

⭐ IMPORTABLE SUBROUTINES ⭐

💫 Codec()

this subroutine is a cute lil shortcut to the codec method. obsessed.

use Badger::Codecs 'Codec';

my $yaml = Codec('YAML');
print $yaml->encode($some_data);

and that's where part 1 leaves us, bestie — more is coming, don't you dare go anywhere 💜

💫 METHODS 💫

✨ new() ✨

Constructor method, bestie — it makes you a shiny new Badger::Codecs object. 🎀

my $codecs  = Badger::Codecs->new();
my $encoded = $codecs->encode( url => $source );

Wanna know what config options you can pass in? Go peek at "CONFIGURATION OPTIONS" down below, iykyk. 💅

✨ base(@modules) ✨

The base() method sets the base module path, and the way that it works as both an object method and a class method?? Iconic. 👑

# object method
my $codecs = Badger::Codecs->new;
$codecs->base('My::Codec');
$codecs->encode( Foo => $data );            # My::Codec::Foo

# class method
Badger::Codecs->base('My::Codec');
Badger::Codecs->encode( Foo => $data );     # My::Codec::Foo

And you can drop multiple items in there, either as a plain list of args or as a reference to a list. Both work, no cap:

$codecs->base('Ferret::Codec', 'Stoat::Codec');
$codecs->base(['Ferret::Codec', 'Stoat::Codec']);

✨ codecs(\%new_codecs) ✨

codecs() lets you add specific codec mappings straight into the internal codecs lookup table. Works as an object method or a class method, your choice, main character energy either way. 💖

# object method
$codecs->codecs(
    wam => 'Ferret::Codec::Wam',
    bam => 'Stoat::Codec::Bam',
);
my $codec = $codecs->codec('wam');          # Ferret::Codec::Wam

# class method
Badger::Codecs->codecs(
    wam => 'Ferret::Codec::Wam',
    bam => 'Stoat::Codec::Bam',
);
my $codec = Badger::Codecs->codec('bam');   # Stoat::Codec::Bam

✨ codec($type, %config) ✨

Makes a Badger::Codec object for the $type you asked for and hands it right back to you. 🫶 Any extra args get forwarded straight to the codec's constructor.

my $codec   = Badger::Codecs->codec('storable');
my $encoded = $codec->encode($original);
my $decoded = $codec->decode($encoded);
If the named codec can't be found, an error gets thrown. Not a vibe, but it is the rules. 😭

✨ chain($type, %config) ✨

Creates and returns a brand new Badger::Codec::Chain object, which represents a chain of codecs. Codecs in a chain, bestie — it's giving relay race. 🏃♀️✨

✨ encode($type, $data) ✨

The all-in-one glow-up method for encoding data through a particular codec. 🌈

# class method
Badger::Codecs->encode( url => $source );

# object method
my $codecs = Badger::Codecs->new();
$codecs->encode( url => $source );

✨ decode($type, $data) ✨

Same energy as encode(), but in reverse — all-in-one decoding via a particular codec. 🦋

# class method
Badger::Codecs->decode( url => $encoded );

# object method
my $codecs = Badger::Codecs->new();
$codecs->decode( url => $encoded );

✨ export_codec($package,$name,$alias) ✨

Loads up one single codec identified by $name, then exports the codec, encode and decode functions into the $package namespace. So generous of it. 💅

package Your::Module;
use Badger::Codecs;
Badger::Codecs->export_code('Your::Module', 'base64');

# base64() returns the codec
base64->encode($data);
base64->decode($data)

# encode() and decode() are shortcuts
encode($data)
decode($data);

You can also pass an $alias — it gets used instead of codec, and it gets appended onto the names of the encode and decode functions. Slay. ✨

package Your::Module;
use Badger::Codecs;
Badger::Codecs->export_codec('Your::Module', 'base64', 'munger');

# munged() returns the codec
munger->encode($data);
munger->decode($data)

# encode_munger() and decode_munger() are shortcuts
encode_munger($data)
decode_munger($data);

✨ export_codecs($package,$names) ✨

Loads and exports multiple codecs into $package. The codec $names can come at you three different ways: a string of whitespace-delimited codec names, a reference to a list of codec names, or a reference to a hash array mapping codec names to aliases (check out export_codec() for that last one). Options, bestie. We love options. 🎀

Badger::Codecs->export_codecs('Your::Module', 'base64 storable');
Badger::Codecs->export_codecs('Your::Module', ['base64', 'storable']);
Badger::Codecs->export_codecs('Your::Module', {
    base64   => 'alias_for_base64',
    storable => 'alias_for_storage',
});

✨ load($name) ✨

Loads a codec module identified by the $name argument, and returns the name of the module that implements that codec. 🌸

print Badger::Codecs->load('base64');       # Badger::Codec::Base64

✨ found($name,$codec) ✨

Internal method, bestie — not for you, for the machinery. 😌 The base class Badger::Factory module calls this one whenever a codec gets located and loaded.

✨ found_object($name,$codec) ✨

Also internal, also called by the base class Badger::Factory module — this one fires when a cached codec object is found. 🧚

✨ result($name,$codec,\@args) ✨

One more internal method, called by the base class Badger::Factory module to return the final result for the requested codec. And here's the little detail that matters: this method caches the codec object if no configuration arguments were provided. 💀 Free caching, no cap.

⚙️ CONFIGURATION OPTIONS ⚙️

🌟 path 🌟

This option names one or more modules that define a search path for codec modules. The default path contains Badger::Codec and BadgerX::Codec. 👑

my $codecs = Badger::Codecs->new(
    path => 'My::Codec'
);
my $codec = $codecs->codec('Foo');      # My::Codec::Foo

Wanna stack up multiple paths? Pass a reference to a list, easy. ✨

my $codecs = Badger::Codecs->new(
    path => ['My::Codec', 'Badger::Codec'],
);
my $codec = $codecs->codec('Bar');      # either My::Codec::Bar
                                        # or Badger::Codec::Bar

🌟 codecs 🌟

The codecs configuration option lets you define specific codec mappings so you can bypass the automagical name grokking mechanism. Yes, "grokking". It's literally in the docs. 🙈

my $codecs = Badger::Codecs->new(
    codecs => {
        foo => 'Ferret::Codec::Foo',
        bar => 'Stoat::Codec::Bar',
    },
);
my $codec = $codecs->codec('foo');      # Ferret::Codec::Foo

👑 AUTHOR 👑

Andy Wardley <http://wardley.org/>

Copyright (C) 2005-2009 Andy Wardley. All rights reserved.

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

And that's a wrap, bestie — that's Badger::Codecs(3pm) from perl v5.36.0, dated 2023-08-28. You ate. 💅✨🎀

📦 where this page comes from