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 1;
  17 __END__
  18
  19 =encoding utf-8
  20
  21 =head1 NAME
  22
  23 IO::Uncompress::Brotli - Read Brotli buffers/streams
  24
  25 =head1 SYNOPSIS
  26
  27   use IO::Uncompress::Brotli;
  28
  29   # uncompress a buffer (yielding at most 10MB)
  30   my $decoded = unbro $encoded, 10_000_000;
  31
  32   # uncompress a stream
  33   my $bro = IO::Uncompress::Brotli->create;
  34   while(have_input()) {
  35      my $block = get_input_block();
  36      my $decoded_block = $bro->decompress($block);
  37      handle_output_block($decoded_block);
  38   }
  39
  40 =head1 DESCRIPTION
  41
  42 IO::Uncompress::Brotli is a module that decompresses Brotli buffers
  43 and streams. Despite its name, it is not a subclass of
  44 L<IO::Uncompress::Base> and does not implement its interface. This
  45 will be rectified in a future release.
  46
  47 =head2 One-shot interface
  48
  49 If you have the whole buffer in a Perl scalar use the B<unbro>
  50 function.
  51
  52 =over
  53
  54 =item B<unbro>(I<$input>, I<$maximum_decoded_size>)
  55
  56 Takes a whole compressed buffer as input and returns the decompressed
  57 data. It allocates a buffer of size I<$maximum_decoded_size> to store
  58 the decompressed data, if this is not sufficient (or there is another
  59 error) this function will croak.
  60
  61 Exported by default.
  62
  63 =back
  64
  65 =head2 Streaming interface
  66
  67 If you want to process the data in blocks use the object oriented
  68 interface. The available methods are:
  69
  70 =over
  71
  72 =item IO::Uncompress::Brotli->B<create>
  73
  74 Returns a IO::Uncompress::Brotli instance. Please note that a single
  75 instance cannot be used to decompress multiple streams.
  76
  77 =item $bro->B<decompress>(I<$block>)
  78
  79 Takes the a block of compressed data and returns a block of
  80 uncompressed data. Dies on error.
  81
  82 =back
  83
  84 =head1 SEE ALSO
  85
  86 RFC 7392 Brotli Compressed Data Format:
  87 L<https://tools.ietf.org/html/rfc7932>
  88
  89 Brotli source code: L<https://github.com/google/brotli/>
  90
  91 =head1 AUTHOR
  92
  93 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
  94
  95 The encoder bindings, modernisation of the decoder bindings and a
  96 clean up of the overall project were contributed by:
  97
  98 =over
  99
 100 =item Quim Rovira, E<lt>quim@rovira.catE<gt>
 101
 102 =item Ævar Arnfjörð Bjarmason, E<lt>avarab@gmail.comE<gt>
 103
 104 =item Marcell Szathmári
 105
 106 =item Mattia Barbon, E<lt>mattia@barbon.orgE<gt>
 107
 108 =back
 109
 110 POD fix by Mark Zabaro, E<lt>markzabaro@gmail.comE<gt>.
 111
 112 =head1 COPYRIGHT AND LICENSE
 113
 114 Copyright (C) 2015-2018 by Marius Gavrilescu
 115
 116 This library is free software; you can redistribute it and/or modify
 117 it under the same terms as Perl itself, either Perl version 5.20.2 or,
 118 at your option, any later version of Perl 5 you may have available.
 119
 120
 121 =cut