[io-compress-brotli.git] / lib / IO / Compress / Brotli.pm

package IO::Compress::Brotli;

use 5.014000;
use strict;
use warnings;
use parent qw/Exporter/;

use IO::Uncompress::Brotli;

our @EXPORT = qw/bro/;
our @EXPORT_OK = @EXPORT;

our $VERSION = '0.004001';

my %BROTLI_ENCODER_MODE = ( generic => 0, text => 1, font => 2 );
sub mode {
    my ($self, $mode) = @_;

    die "Invalid encoder mode"
        unless $BROTLI_ENCODER_MODE{$mode};

    _mode($$self, $mode)
}


1;
__END__

=encoding utf-8

=head1 NAME

IO::Compress::Brotli - Write Brotli buffers/streams

=head1 SYNOPSIS

  use IO::Compress::Brotli;

  # compress a buffer
  my $encoded = bro $encoded;

  # compress a stream
  my $bro = IO::Compress::Brotli->create;
  while(have_input()) {
     my $block = get_input_block();
     my $encoded_block = $bro->compress($block);
     handle_output_block($encoded_block);
  }
  # Need to finish the steam
  handle_output_block($bro->finish());

=head1 DESCRIPTION

IO::Compress::Brotli is a module that compressed Brotli buffers
and streams. Despite its name, it is not a subclass of
L<IO::Compress::Base> and does not implement its interface. This
will be rectified in a future release.

=head2 One-shot interface

If you have the whole buffer in a Perl scalar use the B<bro>
function.

=over

=item B<bro>(I<$input>, I<$quality>, I<$window>)

Takes a whole uncompressed buffer as input and returns the compressed
data using the supplied quality and window parameters. If quality and
window parameters are not supplied, default values are used (as
described under the object-oriented interface).

Exported by default.

=back

=head2 Streaming interface

If you want to process the data in blocks use the object oriented
interface. The available methods are:

=over

=item IO::Compress::Brotli->B<create>

Returns a IO::Compress::Brotli instance. Please note that a single
instance cannot be used to decompress multiple streams.

=item $bro->B<window>(I<$window>)

Sets the window parameter on the brotli encoder.
Defaults to BROTLI_DEFAULT_WINDOW (22).

=item $bro->B<quality>(I<$quality>)

Sets the quality paremeter on the brotli encoder.
Defaults to BROTLI_DEFAULT_QUALITY (11).

=item $bro->B<mode>(I<$mode>)

Sets the brotli encoder mode, which can be any of "generic",
"text" or "font". Defaults to "generic".

=item $bro->B<compress>(I<$block>)

Takes the a block of uncompressed data and returns a block of
compressed data. Dies on error.

=item $bro->B<flush>()

Flushes any pending output from the encoder.

=item $bro->B<finish>()

Tells the encoder to start the finish operation, and flushes
any remaining compressed output.

Once finish is called, the encoder cannot be used to compress
any more content.

B<NOTE>: Calling finish is B<required>, or the output might
remain unflushed, and the be missing termination marks.

=back

=head1 SEE ALSO

Brotli Compressed Data Format Internet-Draft:
L<https://www.ietf.org/id/draft-alakuijala-brotli-08.txt>

Brotli source code: L<https://github.com/google/brotli/>

=head1 AUTHOR

Marius Gavrilescu, E<lt>marius@ieval.roE<gt>

The encoder bindings, modernisation of the decoder bindings and a
clean up of the overall project were contributed by:

=over

=item Quim Rovira, E<lt>quim@rovira.catE<gt>

=item Ævar Arnfjörð Bjarmason, E<lt>avarab@gmail.comE<gt>

=item Marcell Szathmári

=item Mattia Barbon, E<lt>mattia@barbon.orgE<gt>

=back

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2015-2018 by Marius Gavrilescu

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself, either Perl version 5.20.2 or,
at your option, any later version of Perl 5 you may have available.


=cut
Commit	Line	Data
	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