lib/Convert/Base91.pm

   1 package Convert::Base91;
   2
   3 use 5.014000;
   4 use strict;
   5 use warnings;
   6 use parent qw/Exporter/;
   7
   8 our @EXPORT_OK = qw/encode_base91 decode_base91/;
   9 our @EXPORT = ();
  10
  11 our $VERSION = '0.001002';
  12
  13 require XSLoader;
  14 XSLoader::load('Convert::Base91', $VERSION);
  15
  16 our $base91 = __PACKAGE__->new;
  17
  18 sub encode_base91 {
  19         my ($data) = @_;
  20         $base91->encode($data);
  21         $base91->encode_end;
  22 }
  23
  24 sub decode_base91 {
  25         my ($data) = @_;
  26         $base91->decode($data);
  27         $base91->decode_end;
  28 }
  29
  30 1;
  31 __END__
  32
  33 =encoding utf-8
  34
  35 =head1 NAME
  36
  37 Convert::Base91 - XS base91 encoding/decoding
  38
  39 =head1 SYNOPSIS
  40
  41   use Convert::Base91 qw/encode_base91 decode_base91/;
  42
  43   # procedural interface
  44   my $encoded = encode_base91 'some data';
  45   say $encoded; # qrLg,W;Hr%w
  46   my $decoded = decode_base91 $encoded;
  47   say $decoded; # some data
  48
  49
  50   # OO interface
  51   my $base91 = Convert::Base91->new;
  52   $base91->encode('some ');
  53   $base91->encode('data');
  54   my $enc = $base91->encode_end;
  55   say $enc; # qrLg,W;Hr%w
  56
  57   $base91->decode('qrLg,');
  58   $base91->decode('W;Hr%w');
  59   my $dec = $base91->decode_end;
  60   say $dec; # some data
  61
  62 =head1 DESCRIPTION
  63
  64 Base91 is a method for encoding binary data as printable ASCII
  65 characters. Every two base91 characters (16 bits) encode 13 or 14 bits
  66 of actual data, thus the overhead is between 14% and 23%, an
  67 improvement over base64's overhead of 33%.
  68
  69 This module provides a procedural interface for encoding/decoding
  70 whole strings and an OO interface for encoding/decoding in chunks.
  71
  72 The C<encode_base91> and C<decode_base91> functions are available for
  73 export, but are not exported by default.
  74
  75 =over
  76
  77 =item B<encode_base91> $binary_data
  78
  79 Takes a string containing arbitrary bytes and returns the
  80 base91 encoded data.
  81
  82 =item B<decode_base91> $base91_data
  83
  84 Takes a string containing base91 encoded data and returns the decoded
  85 string of arbitrary bytes.
  86
  87 =item Convert::Base91->B<new>
  88
  89 Create a new C<Convert::Base91> object to keep the state for a chunk
  90 encoding/decoding operation.
  91
  92 =item $base91->B<encode>($data)
  93
  94 Submit the next chunk of arbitrary binary data to be encoded. Returns
  95 nothing.
  96
  97 =item $base91->B<encode_end>
  98
  99 Signals that all chunks of data to be encoded have been submitted.
 100 Returns the base91 encoded data, and clears the state of the $base91
 101 object so it may be used again (for either encoding or decoding).
 102
 103 =item $base91->B<decode>($data)
 104
 105 Submit the next chunk of base91 data to be decoded. Returns nothing.
 106
 107 =item $base91->B<decode_end>
 108
 109 Signals that all chunks of data to be decoded have been submitted.
 110 Returns the decoded data, and clears the state of the $base91 object
 111 so it may be used again (for either encoding or decoding).
 112
 113 =back
 114
 115 =head1 SEE ALSO
 116
 117 L<http://base91.sourceforge.net/>
 118
 119 =head1 AUTHOR
 120
 121 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 122
 123 =head1 COPYRIGHT AND LICENSE
 124
 125 Copyright (C) 2017 by Marius Gavrilescu
 126
 127 This library is free software; you can redistribute it and/or modify
 128 it under the same terms as Perl itself, either Perl version 5.26.1 or,
 129 at your option, any later version of Perl 5 you may have available.
 130
 131
 132 =cut