lib/IO/Compress/Brotli.pm

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