package CGIpack;
use strict;

=head1 NAME

CGIpack - Transforms parameters into a packed list of URL-compatible characters
and vice versa.

=head1 SYNOPSIS

 use CGIpack;

 # Transform a list of numbers and back. 
 #Results in:
 @data=(15,13,2**23,0,2**31);
 @bitsizes = (4,14,24,1,55 );
 $encoded=encode({ bitsizes=>[@bitsizes], data=>[@data]});
 $decoded=join ', ', decode( {str=>$encoded, bitsizes=>[@bitsizes]} );
 ## only converted 32 bits instead of 55
 #Data: 15, 13, 8388608, 0, 2147483648
 #Encoded: V30000W000004000
 #Decoded array: 15, 13, 8388608, 0, 2147483648
 
=head1 DESCRIPTION

CGIpack is a module I wrote in response to a question.  Question went like: 
"I want my users to save a URL containing a CGI with parameters.  To avoid 
problems with email-readers, the list should be as short as possible, and 
to avoid users messing around with the values I would like to see them 
encoded in a certain way."

I came up with this solution.  The encoder takes a list of data, together 
with a list with the desired number of bits to be saved.  The bits are 
divided into chunks of 6 bits, that are encoded with the alphanumeric 
characters *and* % and - (64 characters in total). The resulting string
is short, contains as little bits as possible and/or desired by the user. 

=over 4

=item encode( $hashref )

Takes a hashref, which should contain a member 'data', referring to a list, 
and a member 'bitsizes', referring to a list containing the number of 
desired bits for every value in the list. 

=item decode( $hashref )

Takes a hashref, which should contain a member 'str', containing a string 
of characters produced by encode (preferably, you may wanna roll your own 
;-) and a member 'bitsizes', referring to a list containing the number of 
desired bits for every value encoded in the string.

=back

=head1 CAVEAT

If you want to encode characters, you will have to convert them manually 
using unpack/pack 'c'.  I just may add a wrapper for that in the future, 
though.

It does work on 32 bit integers, but not yet on 64 bit. I'm a little puzzled
why not, it may have something to do with the fact I'm working on a 32-bit
pentium right now. Will try at home with my PPC.

=head1 AUTHOR

Jeroen Elassaiss-Schaap

=head1 LICENSE

Perl/ artisitic license

=head1 STATUS

Alpha

=cut

use Exporter;
use vars qw( @EXPORT @ISA @VERSION);
@VERSION = 0.021;
@ISA = qw( Exporter );
@EXPORT = qw( &encode &decode);

sub encode{
	my $hash = shift;
	my @data = @{$hash->{'data'}};
	my @bitsizes = @{$hash->{'bitsizes'}};
	my ($str, $bitstr);
	for my $bits (@bitsizes) {
		$bitstr .= unpack("b$bits", pack('VV', shift( @data ) ));
	}
	$bitstr .= '0' x ( length($bitstr) % 6 );
 	for my $item (0..( length($bitstr) / 6 - 1 )){
	 	my $val=pack('b6', substr($bitstr, $item*6, 6) );
	 	for ($val) {
	     	tr	[\100\077\000-\010\011-\043\044-\075]
	     		[\045\055\060-\071\101-\132\141-\172];
			$str.=$_;
		}
 	}
	$str;
}

sub decode{
	my $hash = shift;
	my $str = $hash->{'str'};
	my @bitsizes= @{$hash->{'bitsizes'}};
 	my ($bitstr, $val);
 	my @data;
	for (split //, $str){
		tr	[\045\055\060-\071\101-\132\141-\172]
			[\100\077\000-\010\011-\043\044-\075];
		$bitstr .= unpack("b6",$_); 
	}
	my $pointer = 0;
	for my $bits (@bitsizes) {
		my $val;
		for ($bits) {
			$val = unpack('c',pack("b$_",substr( $bitstr, $pointer, $_ ))), last
				if $bits < 9;
			$val = unpack('v',pack("b$_",substr( $bitstr, $pointer, $_ ))), last
				if $bits < 17;
			$val = unpack('V',pack("b32",substr( $bitstr, $pointer, $_ ))), last
				if $bits < 33;
			if (! eval('{$val = unpack("Q",pack("b$_",substr( '.
					'$bitstr, $pointer, $_ )));1;}') ) {
				warn "only converted 32 bits instead of $_\n";
				$val = unpack('V',pack("b$_",
					substr( $bitstr, $pointer, $_ )));
			}
		}
		push( @data, $val);
	    $pointer += $bits;
	}
	@data;
}

1;