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