Badger::Codecs
- NAME
- SYNOPSIS
- DESCRIPTION
- Using Codecs
- Chained Codecs
- Import Hooks
- IMPORTABLE SUBROUTINES
- Codec()
- METHODS
- new()
- base(@modules)
- codecs(\%new_codecs)
- codec($type, %config)
- chain($type, %config)
- encode($type, $data)
- decode($type, $data)
- export_codec($package,$name,$alias)
- export_codecs($package,$names)
- load($name)
- found($name,$codec)
- found_object($name,$codec)
- result($name,$codec,\@args)
- CONFIGURATION OPTIONS
- path
- codecs
- AUTHOR
- COPYRIGHT
# 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(...);
A codec is an object responsible for encoding and decoding data. This module implements a codec manager to locate, load and instantiate codec objects.
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!
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.
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);
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.
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']);
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
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.
Creates a new Badger::Codec::Chain object to represent a chain of codecs.
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 );
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 );
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);
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', });
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
This is an internal method called by the base class Badger::Factory module when a codec is located and loaded.
This is an internal method called by the base class Badger::Factory module when a cached codec object is found.
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.
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
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
Andy Wardley http://wardley.org/