Provided by: libbadger-perl_0.16-2_all 
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.