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