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.001';
  12
  13 require XSLoader;
  14 XSLoader::load('IO::Compress::Brotli', $VERSION);
  15
  16 sub create {
  17         my ($class) = @_;
  18         my $state = BrotliCreateState();
  19         bless \$state, $class
  20 }
  21
  22 sub DESTROY {
  23         my ($self) = @_;
  24         BrotliDestroyState($$self)
  25 }
  26
  27 sub decompress {
  28         my ($self, $data) = @_;
  29         BrotliDecompressStream($$self, $data)
  30 }
  31
  32 # Untested, probably not working
  33 sub set_dictionary {
  34         my ($self, $dict) = @_;
  35         BrotliSetCustomDictionary($$self, $dict)
  36 }
  37
  38 1;
  39 __END__
  40
  41 =encoding utf-8
  42
  43 =head1 NAME
  44
  45 IO::Uncompress::Brotli - Read Brotli buffers/streams
  46
  47 =head1 SYNOPSIS
  48
  49   use IO::Uncompress::Brotli;
  50
  51   # uncompress a buffer
  52   my $decoded = unbro $encoded;
  53
  54   # uncompress a stream
  55   my $bro = IO::Uncompress::Brotli->create;
  56   while(have_input()) {
  57      my $block = get_input_block();
  58      my $decoded_block = $bro->decompress($block);
  59      handle_output_block($decoded_block);
  60   }
  61
  62 =head1 DESCRIPTION
  63
  64 IO::Uncompress::Brotli is a module that decompresses Brotli buffers
  65 and streams. Despite its name, it is not a subclass of
  66 L<IO::Uncompress::Base> and does not implement its interface. This
  67 will be rectified in a future release.
  68
  69 =head2 One-shot interface
  70
  71 If you have the whole buffer in a Perl scalar use the B<unbro>
  72 function.
  73
  74 =over
  75
  76 =item B<unbro>(I<$input>)
  77
  78 Takes a whole compressed buffer as input and returns the decompressed
  79 data. This function relies on the BrotliDecompressedSize function. In
  80 other words, it only works if the buffer has a single meta block or
  81 two meta-blocks where the first is uncompressed and the second is
  82 empty.
  83
  84 Exported by default.
  85
  86 =back
  87
  88 =head2 Streaming interface
  89
  90 If you want to process the data in blocks use the object oriented
  91 interface. The available methods are:
  92
  93 =over
  94
  95 =item IO::Uncompress::Brotli->B<create>
  96
  97 Returns a IO::Uncompress::Brotli instance. Please note that a single
  98 instance cannot be used to decompress multiple streams.
  99
 100 =item $bro->B<decompress>(I<$block>)
 101
 102 Takes the a block of compressed data and returns a block of
 103 uncompressed data. Dies on error.
 104
 105 =back
 106
 107 =head1 SEE ALSO
 108
 109 Brotli Compressed Data Format Internet-Draft:
 110 L<https://www.ietf.org/id/draft-alakuijala-brotli-08.txt>
 111
 112 Brotli source code: L<https://github.com/google/brotli/>
 113
 114 =head1 AUTHOR
 115
 116 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 117
 118 =head1 COPYRIGHT AND LICENSE
 119
 120 Copyright (C) 2015 by Marius Gavrilescu
 121
 122 This library is free software; you can redistribute it and/or modify
 123 it under the same terms as Perl itself, either Perl version 5.20.2 or,
 124 at your option, any later version of Perl 5 you may have available.
 125
 126
 127 =cut