lib/IO/Uncompress/Brotli.pm

   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.004001';
  12
  13 require XSLoader;
  14 XSLoader::load('IO::Compress::Brotli', $VERSION);
  15
  16 # 0.004 has unbro with prototype $$
  17 # 0.004_001 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_001, 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