lib/IO/Compress/Brotli.pm

   1 package IO::Compress::Brotli;
   2
   3 use 5.014000;
   4 use strict;
   5 use warnings;
   6
   7 use IO::Uncompress::Brotli;
   8
   9 use parent qw/Exporter/;
  10
  11 our @EXPORT = qw/bro/;
  12 our @EXPORT_OK = @EXPORT;
  13
  14 our $VERSION = '0.001001';
  15
  16 sub create {
  17         my ($class) = @_;
  18         my $state = BrotliEncoderCreateInstance();
  19         bless \$state, $class
  20 }
  21
  22 sub DESTROY {
  23         my ($self) = @_;
  24         BrotliEncoderDestroyInstance($$self)
  25 }
  26
  27 sub quality {
  28     my ($self, $quality) = @_;
  29     BrotliEncoderSetQuality($$self, $quality)
  30 }
  31
  32 sub window {
  33     my ($self, $window) = @_;
  34     BrotliEncoderSetWindow($$self, $window)
  35 }
  36
  37 my %BROTLI_ENCODER_MODE = ( generic => 0, text => 1, font => 2 );
  38 sub mode {
  39     my ($self, $mode) = @_;
  40
  41     die "Invalid encoder mode"
  42         unless $BROTLI_ENCODER_MODE{$mode};
  43
  44     BrotliEncoderSetMode($$self, $mode)
  45 }
  46
  47 use constant {
  48     BROTLI_OPERATION_PROCESS => 0,
  49     BROTLI_OPERATION_FLUSH   => 1,
  50     BROTLI_OPERATION_FINISH  => 2
  51 };
  52 sub compress {
  53         my ($self, $data) = @_;
  54         BrotliEncoderCompressStream($$self, $data, BROTLI_OPERATION_PROCESS )
  55 }
  56
  57 sub flush {
  58         my ($self) = @_;
  59         BrotliEncoderCompressStream($$self, '', BROTLI_OPERATION_FLUSH )
  60 }
  61
  62 sub finish {
  63         my ($self) = @_;
  64         BrotliEncoderCompressStream($$self, '', BROTLI_OPERATION_FINISH )
  65 }
  66
  67 # Untested, probably not working
  68 sub set_dictionary {
  69         my ($self, $dict) = @_;
  70         BrotliEncoderSetCustomDictionary($$self, $dict)
  71 }
  72
  73 1;
  74 __END__
  75
  76 =encoding utf-8
  77
  78 =head1 NAME
  79
  80 IO::Compress::Brotli - [Not yet implemented] Write Brotli buffers/streams
  81
  82 =head1 SYNOPSIS
  83
  84   use IO::Compress::Brotli;
  85
  86   # compress a buffer
  87   my $encoded = bro $encoded;
  88
  89   # compress a stream
  90   my $bro = IO::Compress::Brotli->create;
  91   while(have_input()) {
  92      my $block = get_input_block();
  93      my $encoded_block = $bro->compress($block);
  94      handle_output_block($encoded_block);
  95   }
  96   # Need to finish the steam
  97   handle_output_block($bro->finish());
  98
  99 =head1 DESCRIPTION
 100
 101 IO::Compress::Brotli is a module that compressed Brotli buffers
 102 and streams. Despite its name, it is not a subclass of
 103 L<IO::Compress::Base> and does not implement its interface. This
 104 will be rectified in a future release.
 105
 106 =head2 One-shot interface
 107
 108 If you have the whole buffer in a Perl scalar use the B<bro>
 109 function.
 110
 111 =over
 112
 113 =item B<bro>(I<$input>)
 114
 115 Takes a whole uncompressed buffer as input and returns the compressed
 116 data.
 117
 118 Exported by default.
 119
 120 =back
 121
 122 =head2 Streaming interface
 123
 124 If you want to process the data in blocks use the object oriented
 125 interface. The available methods are:
 126
 127 =over
 128
 129 =item IO::Compress::Brotli->B<create>
 130
 131 Returns a IO::Compress::Brotli instance. Please note that a single
 132 instance cannot be used to decompress multiple streams.
 133
 134 =item $bro->B<window>(I<$window>)
 135
 136 Sets the window parameter on the brotli encoder.
 137 Defaults to BROTLI_DEFAULT_WINDOW (22).
 138
 139 =item $bro->B<quality>(I<$quality>)
 140
 141 Sets the quality paremeter on the brotli encoder.
 142 Defaults to BROTLI_DEFAULT_QUALITY (11).
 143
 144 =item $bro->B<mode>(I<$mode>)
 145
 146 Sets the brotli encoder mode, which can be any of "generic",
 147 "text" or "font". Defaults to "generic".
 148
 149 =item $bro->B<compress>(I<$block>)
 150
 151 Takes the a block of uncompressed data and returns a block of
 152 compressed data. Dies on error.
 153
 154 =item $bro->B<flush>()
 155
 156 Flushes any pending output from the encoder.
 157
 158 =item $bro->B<finish>()
 159
 160 Tells the encoder to start the finish operation, and flushes
 161 any remaining compressed output.
 162
 163 Once finish is called, the encoder cannot be used to compress
 164 any more content.
 165
 166 B<NOTE>: Calling finish is B<required>, or the output might
 167 remain unflushed, and the be missing termination marks.
 168
 169 =back
 170
 171 =head1 SEE ALSO
 172
 173 Brotli Compressed Data Format Internet-Draft:
 174 L<https://www.ietf.org/id/draft-alakuijala-brotli-08.txt>
 175
 176 Brotli source code: L<https://github.com/google/brotli/>
 177
 178 =head1 AUTHOR
 179
 180 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 181
 182 =head1 COPYRIGHT AND LICENSE
 183
 184 Copyright (C) 2015 by Marius Gavrilescu
 185
 186 This library is free software; you can redistribute it and/or modify
 187 it under the same terms as Perl itself, either Perl version 5.20.2 or,
 188 at your option, any later version of Perl 5 you may have available.
 189
 190
 191 =cut