]>
Commit | Line | Data |
---|---|---|
1 | package IO::Uncompress::Brotli; | |
2 | ||
3 | use 5.014000; | |
4 | use strict; | |
5 | use warnings; | |
6 | use parent qw/Exporter/; | |
7 | ||
8 | our @EXPORT = qw/unbro/; | |
9 | our @EXPORT_OK = @EXPORT; | |
10 | ||
11 | our $VERSION = '0.004_002'; | |
12 | ||
13 | require XSLoader; | |
14 | XSLoader::load('IO::Compress::Brotli', $VERSION); | |
15 | ||
16 | # 0.004001 has unbro with prototype $$ | |
17 | # 0.004_002 renames it to unbro_given_size, and provides unbro with | |
18 | # prototype $;$ which calls: | |
19 | # * unbro_given_size when called with two arguments | |
20 | # * the OO interface when called with one argument | |
21 | sub unbro ($;$) { | |
22 | my ($buffer, $decoded_size) = @_; | |
23 | if (defined $decoded_size) { | |
24 | return unbro_given_size($buffer, $decoded_size) | |
25 | } else { | |
26 | my $bro = IO::Uncompress::Brotli->create; | |
27 | return $bro->decompress($buffer); | |
28 | } | |
29 | } | |
30 | ||
31 | 1; | |
32 | __END__ | |
33 | ||
34 | =encoding utf-8 | |
35 | ||
36 | =head1 NAME | |
37 | ||
38 | IO::Uncompress::Brotli - Read Brotli buffers/streams | |
39 | ||
40 | =head1 SYNOPSIS | |
41 | ||
42 | use IO::Uncompress::Brotli; | |
43 | ||
44 | # uncompress a buffer (yielding at most 10MB) | |
45 | my $decoded = unbro $encoded, 10_000_000; | |
46 | ||
47 | # uncompress a stream | |
48 | my $bro = IO::Uncompress::Brotli->create; | |
49 | while(have_input()) { | |
50 | my $block = get_input_block(); | |
51 | my $decoded_block = $bro->decompress($block); | |
52 | handle_output_block($decoded_block); | |
53 | } | |
54 | ||
55 | =head1 DESCRIPTION | |
56 | ||
57 | IO::Uncompress::Brotli is a module that decompresses Brotli buffers | |
58 | and streams. Despite its name, it is not a subclass of | |
59 | L<IO::Uncompress::Base> and does not implement its interface. This | |
60 | will be rectified in a future release. | |
61 | ||
62 | =head2 One-shot interface | |
63 | ||
64 | If you have the whole buffer in a Perl scalar use the B<unbro> | |
65 | function. | |
66 | ||
67 | =over | |
68 | ||
69 | =item B<unbro>(I<$input>, I<$maximum_decoded_size>) | |
70 | ||
71 | Takes a whole compressed buffer as input and returns the decompressed | |
72 | data. It allocates a buffer of size I<$maximum_decoded_size> to store | |
73 | the decompressed data, if this is not sufficient (or there is another | |
74 | error) this function will croak. | |
75 | ||
76 | As of version 0.004_002, the I<$maximum_decoded_size> argument is | |
77 | optional. If not provided, B<unbro> uses the streaming interface | |
78 | described in the next section to decompress the buffer in blocks of | |
79 | one megabyte. The decompressed blocks are concatenated and returned. | |
80 | ||
81 | Exported by default. | |
82 | ||
83 | =back | |
84 | ||
85 | =head2 Streaming interface | |
86 | ||
87 | If you want to process the data in blocks use the object oriented | |
88 | interface. The available methods are: | |
89 | ||
90 | =over | |
91 | ||
92 | =item IO::Uncompress::Brotli->B<create> | |
93 | ||
94 | Returns a IO::Uncompress::Brotli instance. Please note that a single | |
95 | instance cannot be used to decompress multiple streams. | |
96 | ||
97 | =item $bro->B<decompress>(I<$block>) | |
98 | ||
99 | Takes the a block of compressed data and returns a block of | |
100 | uncompressed data. Dies on error. | |
101 | ||
102 | =back | |
103 | ||
104 | =head1 SEE ALSO | |
105 | ||
106 | RFC 7392 Brotli Compressed Data Format: | |
107 | L<https://tools.ietf.org/html/rfc7932> | |
108 | ||
109 | Brotli source code: L<https://github.com/google/brotli/> | |
110 | ||
111 | =head1 AUTHOR | |
112 | ||
113 | Marius Gavrilescu, E<lt>marius@ieval.roE<gt> | |
114 | ||
115 | The encoder bindings, modernisation of the decoder bindings and a | |
116 | clean up of the overall project were contributed by: | |
117 | ||
118 | =over | |
119 | ||
120 | =item Quim Rovira, E<lt>quim@rovira.catE<gt> | |
121 | ||
122 | =item Ævar Arnfjörð Bjarmason, E<lt>avarab@gmail.comE<gt> | |
123 | ||
124 | =item Marcell Szathmári | |
125 | ||
126 | =item Mattia Barbon, E<lt>mattia@barbon.orgE<gt> | |
127 | ||
128 | =back | |
129 | ||
130 | POD fix by Mark Zabaro, E<lt>markzabaro@gmail.comE<gt>. | |
131 | ||
132 | =head1 COPYRIGHT AND LICENSE | |
133 | ||
134 | Copyright (C) 2015-2018 by Marius Gavrilescu | |
135 | ||
136 | This library is free software; you can redistribute it and/or modify | |
137 | it under the same terms as Perl itself, either Perl version 5.20.2 or, | |
138 | at your option, any later version of Perl 5 you may have available. | |
139 | ||
140 | ||
141 | =cut |