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.003_001';
  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>)
  67
  68 Takes a whole uncompressed buffer as input and returns the compressed
  69 data.
  70
  71 Exported by default.
  72
  73 =back
  74
  75 =head2 Streaming interface
  76
  77 If you want to process the data in blocks use the object oriented
  78 interface. The available methods are:
  79
  80 =over
  81
  82 =item IO::Compress::Brotli->B<create>
  83
  84 Returns a IO::Compress::Brotli instance. Please note that a single
  85 instance cannot be used to decompress multiple streams.
  86
  87 =item $bro->B<window>(I<$window>)
  88
  89 Sets the window parameter on the brotli encoder.
  90 Defaults to BROTLI_DEFAULT_WINDOW (22).
  91
  92 =item $bro->B<quality>(I<$quality>)
  93
  94 Sets the quality paremeter on the brotli encoder.
  95 Defaults to BROTLI_DEFAULT_QUALITY (11).
  96
  97 =item $bro->B<mode>(I<$mode>)
  98
  99 Sets the brotli encoder mode, which can be any of "generic",
 100 "text" or "font". Defaults to "generic".
 101
 102 =item $bro->B<compress>(I<$block>)
 103
 104 Takes the a block of uncompressed data and returns a block of
 105 compressed data. Dies on error.
 106
 107 =item $bro->B<flush>()
 108
 109 Flushes any pending output from the encoder.
 110
 111 =item $bro->B<finish>()
 112
 113 Tells the encoder to start the finish operation, and flushes
 114 any remaining compressed output.
 115
 116 Once finish is called, the encoder cannot be used to compress
 117 any more content.
 118
 119 B<NOTE>: Calling finish is B<required>, or the output might
 120 remain unflushed, and the be missing termination marks.
 121
 122 =back
 123
 124 =head1 SEE ALSO
 125
 126 Brotli Compressed Data Format Internet-Draft:
 127 L<https://www.ietf.org/id/draft-alakuijala-brotli-08.txt>
 128
 129 Brotli source code: L<https://github.com/google/brotli/>
 130
 131 =head1 AUTHOR
 132
 133 Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
 134
 135 The encoder bindings, modernisation of the decoder bindings and a
 136 clean up of the overall project were contributed by:
 137
 138 =over
 139
 140 =item Quim Rovira, E<lt>quim@rovira.catE<gt>
 141
 142 =item Ævar Arnfjörð Bjarmason, E<lt>avarab@gmail.comE<gt>
 143
 144 =item Marcell Szathmári
 145
 146 =item Mattia Barbon, E<lt>mattia@barbon.orgE<gt>
 147
 148 =back
 149
 150 =head1 COPYRIGHT AND LICENSE
 151
 152 Copyright (C) 2015-2017 by Marius Gavrilescu
 153
 154 This library is free software; you can redistribute it and/or modify
 155 it under the same terms as Perl itself, either Perl version 5.20.2 or,
 156 at your option, any later version of Perl 5 you may have available.
 157
 158
 159 =cut