---
name: "Badger::Codecs"
section: "3pm"
platform: "linux"
package: "libbadger-perl"
version: "0.16-3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Badger::Codecs"
---

# Badger::Codecs(3pm)

modules for encoding and decoding data

## NAME

Badger::Codecs - modules for encoding and decoding data

## SYNOPSIS

```
    # 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);
    # 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);
    # 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);
    # 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(...);
    # import a codec chain
    use Badger::Codecs
        codec => 'storable+base64';

    # as before, now both codecs are applied
    codec->encode(...);
    codec->decode(...);
    encode(...);
    decode(...)
    # 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(...);
    # 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

A *codec* is an object responsible for encoding and decoding data. This module implements a codec manager to locate, load and instantiate codec objects.

### Using Codecs

First you need to load the `"Badger::Codecs"` module.

```
    use Badger::Codecs;
```

It can be used in regular OO style by first creating a `"Badger::Codecs"` object and then calling methods on it.

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

You can also call class methods directly.

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

Or like this:

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

These examples are the equivalent of:

```
    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 best to locate and load the correct codec module for you. It defines a module base path (containing `"Badger::Codec"` and `"BadgerX::Codec"` by default) to which the name of the requested codec is appended in various forms.

It first tries the name exactly as specified.  If no corresponding codec module is found then it tries a capitalised version of the name, followed by an upper case version of the name.  So if you ask for a `"foo"` codec, then you'll get back a `"Badger::Codec::foo"`, `"Badger::Codec::Foo"`, `"Badger::Codec::FOO"` or an error will be thrown if none of these can be found.

NOTE: the above paragaph is incorrect.  It now tries the capitalised version first to work around Apple's case-insensitive file system.  This is subject to change.

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

Codecs can be chained together in sequence. Specify the names of the individual codes separated by `"+"` characters. Whitespace between the names and `"+"` is optional. The codec chain returned (Badger::Codec::Chain) behaves exactly like any other codec. The only difference being that it is apply several codecs in sequence.

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

Note that the decoding process for a chain happens in reverse order to ensure that a round trip between **encode()** and **decode()** returns the original unencoded data.

### Import Hooks

The `"codec"` and `"codecs"` import hooks can be used to load and define codec subroutines into another module.

```
    package My::Module;

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

The `"codec"` import hook defines a `"codec()"` subroutine which returns a  reference to a codec object.  It also defined `"encode()"` and `"decode()"` subroutines which are mapped to the codec.

```
    # 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 allows you to define several codecs at once. A subroutine is generated to reference each codec, along with encoding and decoding subroutines.

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

You can define alternate names for codecs by providing a reference to a hash array.

```
    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 can be used as a shortcut to the codec method.

```
    use Badger::Codecs 'Codec';

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

## METHODS

### new()

Constructor method to create a new `"Badger::Codecs"` object.

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

See "CONFIGURATION OPTIONS" for details of the configuration options that can be specified.

### base(@modules)

The **base()** method can be used to set the base module path.  It can be called as an object or class method.

```
    # 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
```

Multiple items can be specified as a list of arguments or by reference  to a list.

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

### codecs(\\%new\_codecs)

The **codecs()** method can be used to add specific codec mappings to the internal `"codecs"` lookup table.  It can be called as an object method or a class method.

```
    # 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)

Creates and returns a `"Badger::Codec"` object for the specified `$type`.  Any additional arguments are forwarded to the codec's  constructor method.

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

If the named codec cannot be found then an error is thrown.

### chain($type, %config)

Creates a new Badger::Codec::Chain object to represent a chain of codecs.

### encode($type, $data)

All-in-one method for encoding data via a particular codec.

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

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

### decode($type, $data)

All-in-one method for decoding data 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 a single codec identified by `$name` and exports the `"codec"`, `"encode"` and `"decode"` functions into the `$package` namespace.

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

An `$alias` can be provided which will be used instead of `"codec"` and  appended to the names of the `"encode"` and `"decode"` functions.

```
    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 be specified as a 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 (see **export\_codec()**).

```
    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.  Returns the  name of the module implementing the codec.

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

### found($name,$codec)

This is an internal method called by the base class Badger::Factory module when a codec is located and loaded.

### found\_object($name,$codec)

This is an internal method called by the base class Badger::Factory module when a cached codec object is found.

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

This is an internal method called by the base class Badger::Factory module to return a final result for the requested code.  This method caches the codec object if no configuration arguments were provided.

## CONFIGURATION OPTIONS

### path

This option can be used to specify the name(s) of one or more modules which 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
```

Multiple paths can be specified using a reference to a list.

```
    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 can be used to define specific codec mappings to bypass the automagical name grokking mechanism.

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

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.