]>
Commit | Line | Data |
---|---|---|
1 | package IO::Compress::Brotli; | |
2 | ||
3 | use 5.014000; | |
4 | use strict; | |
5 | use warnings; | |
6 | use parent qw/Exporter/; | |
7 | ||
8 | use Carp qw/croak/; | |
9 | ||
10 | use IO::Uncompress::Brotli; | |
11 | ||
12 | our @EXPORT = qw/bro/; | |
13 | our @EXPORT_OK = @EXPORT; | |
14 | ||
15 | our $VERSION = '0.004_002'; | |
16 | ||
17 | my %BROTLI_ENCODER_MODE = ( generic => 0, text => 1, font => 2 ); | |
18 | sub mode { | |
19 | my ($self, $mode) = @_; | |
20 | ||
21 | croak 'Invalid encoder mode' | |
22 | unless $BROTLI_ENCODER_MODE{$mode}; | |
23 | ||
24 | _mode($$self, $mode) | |
25 | } | |
26 | ||
27 | ||
28 | 1; | |
29 | __END__ | |
30 | ||
31 | =encoding utf-8 | |
32 | ||
33 | =head1 NAME | |
34 | ||
35 | IO::Compress::Brotli - Write Brotli buffers/streams | |
36 | ||
37 | =head1 SYNOPSIS | |
38 | ||
39 | use IO::Compress::Brotli; | |
40 | ||
41 | # compress a buffer | |
42 | my $encoded = bro $encoded; | |
43 | ||
44 | # compress a stream | |
45 | my $bro = IO::Compress::Brotli->create; | |
46 | while(have_input()) { | |
47 | my $block = get_input_block(); | |
48 | my $encoded_block = $bro->compress($block); | |
49 | handle_output_block($encoded_block); | |
50 | } | |
51 | # Need to finish the steam | |
52 | handle_output_block($bro->finish()); | |
53 | ||
54 | =head1 DESCRIPTION | |
55 | ||
56 | IO::Compress::Brotli is a module that compressed Brotli buffers | |
57 | and streams. Despite its name, it is not a subclass of | |
58 | L<IO::Compress::Base> and does not implement its interface. This | |
59 | will be rectified in a future release. | |
60 | ||
61 | =head2 One-shot interface | |
62 | ||
63 | If you have the whole buffer in a Perl scalar use the B<bro> | |
64 | function. | |
65 | ||
66 | =over | |
67 | ||
68 | =item B<bro>(I<$input>, I<$quality>, I<$window>) | |
69 | ||
70 | Takes a whole uncompressed buffer as input and returns the compressed | |
71 | data using the supplied quality and window parameters. If quality and | |
72 | window parameters are not supplied, default values are used (as | |
73 | described under the object-oriented interface). | |
74 | ||
75 | Exported by default. | |
76 | ||
77 | =back | |
78 | ||
79 | =head2 Streaming interface | |
80 | ||
81 | If you want to process the data in blocks use the object oriented | |
82 | interface. The available methods are: | |
83 | ||
84 | =over | |
85 | ||
86 | =item IO::Compress::Brotli->B<create> | |
87 | ||
88 | Returns a IO::Compress::Brotli instance. Please note that a single | |
89 | instance cannot be used to decompress multiple streams. | |
90 | ||
91 | =item $bro->B<window>(I<$window>) | |
92 | ||
93 | Sets the window parameter on the brotli encoder. | |
94 | Defaults to BROTLI_DEFAULT_WINDOW (22). | |
95 | ||
96 | =item $bro->B<quality>(I<$quality>) | |
97 | ||
98 | Sets the quality paremeter on the brotli encoder. | |
99 | Defaults to BROTLI_DEFAULT_QUALITY (11). | |
100 | ||
101 | =item $bro->B<mode>(I<$mode>) | |
102 | ||
103 | Sets the brotli encoder mode, which can be any of "generic", | |
104 | "text" or "font". Defaults to "generic". | |
105 | ||
106 | =item $bro->B<compress>(I<$block>) | |
107 | ||
108 | Takes the a block of uncompressed data and returns a block of | |
109 | compressed data. Dies on error. | |
110 | ||
111 | =item $bro->B<flush>() | |
112 | ||
113 | Flushes any pending output from the encoder. | |
114 | ||
115 | =item $bro->B<finish>() | |
116 | ||
117 | Tells the encoder to start the finish operation, and flushes | |
118 | any remaining compressed output. | |
119 | ||
120 | Once finish is called, the encoder cannot be used to compress | |
121 | any more content. | |
122 | ||
123 | B<NOTE>: Calling finish is B<required>, or the output might | |
124 | remain unflushed, and the be missing termination marks. | |
125 | ||
126 | =back | |
127 | ||
128 | =head1 SEE ALSO | |
129 | ||
130 | Brotli Compressed Data Format Internet-Draft: | |
131 | L<https://www.ietf.org/id/draft-alakuijala-brotli-08.txt> | |
132 | ||
133 | Brotli source code: L<https://github.com/google/brotli/> | |
134 | ||
135 | =head1 AUTHOR | |
136 | ||
137 | Marius Gavrilescu, E<lt>marius@ieval.roE<gt> | |
138 | ||
139 | The encoder bindings, modernisation of the decoder bindings and a | |
140 | clean up of the overall project were contributed by: | |
141 | ||
142 | =over | |
143 | ||
144 | =item Quim Rovira, E<lt>quim@rovira.catE<gt> | |
145 | ||
146 | =item Ævar Arnfjörð Bjarmason, E<lt>avarab@gmail.comE<gt> | |
147 | ||
148 | =item Marcell Szathmári | |
149 | ||
150 | =item Mattia Barbon, E<lt>mattia@barbon.orgE<gt> | |
151 | ||
152 | =back | |
153 | ||
154 | =head1 COPYRIGHT AND LICENSE | |
155 | ||
156 | Copyright (C) 2015-2018 by Marius Gavrilescu | |
157 | ||
158 | This library is free software; you can redistribute it and/or modify | |
159 | it under the same terms as Perl itself, either Perl version 5.20.2 or, | |
160 | at your option, any later version of Perl 5 you may have available. | |
161 | ||
162 | ||
163 | =cut |