Commit | Line | Data |
---|---|---|
f9995f31 MG |
1 | package IO::Compress::Brotli; |
2 | ||
3 | use 5.014000; | |
4 | use strict; | |
5 | use warnings; | |
6 | ||
09cf7186 QR |
7 | use IO::Uncompress::Brotli; |
8 | ||
9 | use parent qw/Exporter/; | |
10 | ||
11 | our @EXPORT = qw/bro/; | |
12 | our @EXPORT_OK = @EXPORT; | |
13 | ||
9d4f189a | 14 | our $VERSION = '0.001001'; |
f9995f31 | 15 | |
09cf7186 QR |
16 | sub create { |
17 | my ($class) = @_; | |
18 | my $state = BrotliEncoderCreateInstance(); | |
19 | bless \$state, $class | |
20 | } | |
21 | ||
22 | sub DESTROY { | |
23 | my ($self) = @_; | |
24 | BrotliEncoderDestroyInstance($$self) | |
25 | } | |
26 | ||
27 | sub quality { | |
28 | my ($self, $quality) = @_; | |
29 | BrotliEncoderSetQuality($$self, $quality) | |
30 | } | |
31 | ||
32 | sub window { | |
33 | my ($self, $window) = @_; | |
34 | BrotliEncoderSetWindow($$self, $window) | |
35 | } | |
36 | ||
37 | my %BROTLI_ENCODER_MODE = ( generic => 0, text => 1, font => 2 ); | |
38 | sub mode { | |
39 | my ($self, $mode) = @_; | |
40 | ||
41 | die "Invalid encoder mode" | |
42 | unless $BROTLI_ENCODER_MODE{$mode}; | |
43 | ||
44 | BrotliEncoderSetMode($$self, $mode) | |
45 | } | |
46 | ||
47 | use constant { | |
48 | BROTLI_OPERATION_PROCESS => 0, | |
49 | BROTLI_OPERATION_FLUSH => 1, | |
50 | BROTLI_OPERATION_FINISH => 2 | |
51 | }; | |
52 | sub compress { | |
53 | my ($self, $data) = @_; | |
54 | BrotliEncoderCompressStream($$self, $data, BROTLI_OPERATION_PROCESS ) | |
55 | } | |
56 | ||
57 | sub flush { | |
58 | my ($self) = @_; | |
59 | BrotliEncoderCompressStream($$self, '', BROTLI_OPERATION_FLUSH ) | |
60 | } | |
61 | ||
62 | sub finish { | |
63 | my ($self) = @_; | |
64 | BrotliEncoderCompressStream($$self, '', BROTLI_OPERATION_FINISH ) | |
65 | } | |
66 | ||
67 | # Untested, probably not working | |
68 | sub set_dictionary { | |
69 | my ($self, $dict) = @_; | |
70 | BrotliEncoderSetCustomDictionary($$self, $dict) | |
71 | } | |
72 | ||
f9995f31 MG |
73 | 1; |
74 | __END__ | |
75 | ||
76 | =encoding utf-8 | |
77 | ||
78 | =head1 NAME | |
79 | ||
80 | IO::Compress::Brotli - [Not yet implemented] Write Brotli buffers/streams | |
81 | ||
82 | =head1 SYNOPSIS | |
83 | ||
84 | use IO::Compress::Brotli; | |
85 | ||
09cf7186 QR |
86 | # compress a buffer |
87 | my $encoded = bro $encoded; | |
88 | ||
89 | # compress a stream | |
90 | my $bro = IO::Compress::Brotli->create; | |
91 | while(have_input()) { | |
92 | my $block = get_input_block(); | |
93 | my $encoded_block = $bro->compress($block); | |
94 | handle_output_block($encoded_block); | |
95 | } | |
96 | # Need to finish the steam | |
97 | handle_output_block($bro->finish()); | |
98 | ||
f9995f31 MG |
99 | =head1 DESCRIPTION |
100 | ||
09cf7186 QR |
101 | IO::Compress::Brotli is a module that compressed Brotli buffers |
102 | and streams. Despite its name, it is not a subclass of | |
103 | L<IO::Compress::Base> and does not implement its interface. This | |
104 | will be rectified in a future release. | |
105 | ||
106 | =head2 One-shot interface | |
107 | ||
108 | If you have the whole buffer in a Perl scalar use the B<bro> | |
109 | function. | |
110 | ||
111 | =over | |
112 | ||
113 | =item B<bro>(I<$input>) | |
114 | ||
115 | Takes a whole uncompressed buffer as input and returns the compressed | |
116 | data. | |
117 | ||
118 | Exported by default. | |
119 | ||
120 | =back | |
121 | ||
122 | =head2 Streaming interface | |
123 | ||
124 | If you want to process the data in blocks use the object oriented | |
125 | interface. The available methods are: | |
126 | ||
127 | =over | |
128 | ||
129 | =item IO::Compress::Brotli->B<create> | |
130 | ||
131 | Returns a IO::Compress::Brotli instance. Please note that a single | |
132 | instance cannot be used to decompress multiple streams. | |
133 | ||
134 | =item $bro->B<window>(I<$window>) | |
135 | ||
136 | Sets the window parameter on the brotli encoder. | |
137 | Defaults to BROTLI_DEFAULT_WINDOW (22). | |
138 | ||
139 | =item $bro->B<quality>(I<$quality>) | |
140 | ||
141 | Sets the quality paremeter on the brotli encoder. | |
142 | Defaults to BROTLI_DEFAULT_QUALITY (11). | |
143 | ||
144 | =item $bro->B<mode>(I<$mode>) | |
145 | ||
146 | Sets the brotli encoder mode, which can be any of "generic", | |
147 | "text" or "font". Defaults to "generic". | |
148 | ||
149 | =item $bro->B<compress>(I<$block>) | |
150 | ||
151 | Takes the a block of uncompressed data and returns a block of | |
152 | compressed data. Dies on error. | |
153 | ||
154 | =item $bro->B<flush>() | |
155 | ||
156 | Flushes any pending output from the encoder. | |
157 | ||
158 | =item $bro->B<finish>() | |
159 | ||
160 | Tells the encoder to start the finish operation, and flushes | |
161 | any remaining compressed output. | |
162 | ||
163 | Once finish is called, the encoder cannot be used to compress | |
164 | any more content. | |
165 | ||
166 | B<NOTE>: Calling finish is B<required>, or the output might | |
167 | remain unflushed, and the be missing termination marks. | |
168 | ||
169 | =back | |
170 | ||
171 | =head1 SEE ALSO | |
172 | ||
173 | Brotli Compressed Data Format Internet-Draft: | |
174 | L<https://www.ietf.org/id/draft-alakuijala-brotli-08.txt> | |
175 | ||
176 | Brotli source code: L<https://github.com/google/brotli/> | |
f9995f31 MG |
177 | |
178 | =head1 AUTHOR | |
179 | ||
180 | Marius Gavrilescu, E<lt>marius@ieval.roE<gt> | |
181 | ||
182 | =head1 COPYRIGHT AND LICENSE | |
183 | ||
184 | Copyright (C) 2015 by Marius Gavrilescu | |
185 | ||
186 | This library is free software; you can redistribute it and/or modify | |
187 | it under the same terms as Perl itself, either Perl version 5.20.2 or, | |
188 | at your option, any later version of Perl 5 you may have available. | |
189 | ||
190 | ||
191 | =cut |