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