Commit | Line | Data |
---|---|---|
1a1c8cd6 MG |
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 | ||
c4b02e1a | 11 | our $VERSION = '1.000'; |
1a1c8cd6 MG |
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 | |
c4b02e1a MG |
85 | string of arbitrary bytes. Any non-printable character in the input is |
86 | silently ignored. | |
1a1c8cd6 MG |
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. | |
c4b02e1a | 107 | Any non-printable character in the input is silently ignored. |
1a1c8cd6 MG |
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 | ||
c4b02e1a MG |
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 | ||
1a1c8cd6 MG |
125 | =head1 AUTHOR |
126 | ||
127 | Marius Gavrilescu, E<lt>marius@ieval.roE<gt> | |
128 | ||
129 | =head1 COPYRIGHT AND LICENSE | |
130 | ||
c4b02e1a | 131 | Copyright (C) 2017-2018 by Marius Gavrilescu |
1a1c8cd6 MG |
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 |