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 = '1.000';
  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. Any non-printable character in the input is
  86 silently ignored.
  87
  88 =item Convert::Base91->B<new>
  89
  90 Create a new C<Convert::Base91> object to keep the state for a chunk
  91 encoding/decoding operation.
  92
  93 =item $base91->B<encode>($data)
  94
  95 Submit the next chunk of arbitrary binary data to be encoded. Returns
  96 nothing.
  97
  98 =item $base91->B<encode_end>
  99
 100 Signals that all chunks of data to be encoded have been submitted.
 101 Returns the base91 encoded data, and clears the state of the $base91
 102 object so it may be used again (for either encoding or decoding).
 103
 104 =item $base91->B<decode>($data)
 105
 106 Submit the next chunk of base91 data to be decoded. Returns nothing.
 107 Any non-printable character in the input is silently ignored.
 108
 109 =item $base91->B<decode_end>
 110
 111 Signals that all chunks of data to be decoded have been submitted.
 112 Returns the decoded data, and clears the state of the $base91 object
 113 so it may be used again (for either encoding or decoding).
 114
 115 =back
 116
 117 =head1 SEE ALSO
 118
 119 L<http://base91.sourceforge.net/>
 120
 121 L<Convert::Ascii85> provides a constant-length encoding, at the cost
 122 of a larger overhead (25% for Ascii85, versus 33% for base64 and
 123 14-23% for base91).
 124
 125 =head1 AUTHOR
 126
 127 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 128
 129 =head1 COPYRIGHT AND LICENSE
 130
 131 Copyright (C) 2017-2018 by Marius Gavrilescu
 132
 133 This library is free software; you can redistribute it and/or modify
 134 it under the same terms as Perl itself, either Perl version 5.26.1 or,
 135 at your option, any later version of Perl 5 you may have available.
 136
 137
 138 =cut