Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Badger::Codecs(3)     User Contributed Perl Documentation    Badger::Codecs(3)

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.

perl v5.32.0			  2016-12-12		     Badger::Codecs(3)

NAME | SYNOPSIS | DESCRIPTION | IMPORTABLE SUBROUTINES | METHODS | CONFIGURATION OPTIONS | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Badger::Codecs&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help