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

package IO::Uncompress::Brotli;

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

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

our $VERSION = '0.003001';

require XSLoader;
XSLoader::load('IO::Compress::Brotli', $VERSION);

1;
__END__

=encoding utf-8

=head1 NAME

IO::Uncompress::Brotli - Read Brotli buffers/streams

=head1 SYNOPSIS

  use IO::Uncompress::Brotli;

  # uncompress a buffer (yielding at most 10MB)
  my $decoded = unbro $encoded, 10_000_000;

  # uncompress a stream
  my $bro = IO::Uncompress::Brotli->create;
  while(have_input()) {
     my $block = get_input_block();
     my $decoded_block = $bro->decompress($block);
     handle_output_block($decoded_block);
  }

=head1 DESCRIPTION

IO::Uncompress::Brotli is a module that decompresses Brotli buffers
and streams. Despite its name, it is not a subclass of
L<IO::Uncompress::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<unbro>
function.

=over

=item B<unbro>(I<$input>, I<$maximum_decoded_size>)

Takes a whole compressed buffer as input and returns the decompressed
data. It allocates a buffer of size I<$maximum_decoded_size> to store
the decompressed data, if this is not sufficient (or there is another
error) this function will croak.

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::Uncompress::Brotli->B<create>

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

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

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

=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-2017 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
f9995f31 MG	1	package IO::Uncompress::Brotli;
	2
	3	use 5.014000;
	4	use strict;
	5	use warnings;
	6	use parent qw/Exporter/;
	7
	8	our @EXPORT = qw/unbro/;
	9	our @EXPORT_OK = @EXPORT;
	10
c4002818	11	our $VERSION = '0.003001';
f9995f31 MG	12
	13	require XSLoader;
	14	XSLoader::load('IO::Compress::Brotli', $VERSION);
	15
f9995f31 MG	16	1;
	17	__END__
	18
	19	=encoding utf-8
	20
	21	=head1 NAME
	22
	23	IO::Uncompress::Brotli - Read Brotli buffers/streams
	24
	25	=head1 SYNOPSIS
	26
	27	use IO::Uncompress::Brotli;
	28
56bfd9c0 MG	29	# uncompress a buffer (yielding at most 10MB)
56bfd9c0 MG	30	my $decoded = unbro $encoded, 10_000_000;
f9995f31 MG	31
	32	# uncompress a stream
	33	my $bro = IO::Uncompress::Brotli->create;
	34	while(have_input()) {
	35	my $block = get_input_block();
	36	my $decoded_block = $bro->decompress($block);
	37	handle_output_block($decoded_block);
	38	}
	39
	40	=head1 DESCRIPTION
	41
	42	IO::Uncompress::Brotli is a module that decompresses Brotli buffers
	43	and streams. Despite its name, it is not a subclass of
	44	L<IO::Uncompress::Base> and does not implement its interface. This
	45	will be rectified in a future release.
	46
	47	=head2 One-shot interface
	48
	49	If you have the whole buffer in a Perl scalar use the B<unbro>
	50	function.
	51
	52	=over
	53
56bfd9c0	54	=item B<unbro>(I<$input>, I<$maximum_decoded_size>)
f9995f31 MG	55
f9995f31 MG	56	Takes a whole compressed buffer as input and returns the decompressed
56bfd9c0 MG	57	data. It allocates a buffer of size I<$maximum_decoded_size> to store
	58	the decompressed data, if this is not sufficient (or there is another
	59	error) this function will croak.
f9995f31 MG	60
	61	Exported by default.
	62
	63	=back
	64
	65	=head2 Streaming interface
	66
	67	If you want to process the data in blocks use the object oriented
	68	interface. The available methods are:
	69
	70	=over
	71
	72	=item IO::Uncompress::Brotli->B<create>
	73
	74	Returns a IO::Uncompress::Brotli instance. Please note that a single
	75	instance cannot be used to decompress multiple streams.
	76
	77	=item $bro->B<decompress>(I<$block>)
	78
	79	Takes the a block of compressed data and returns a block of
	80	uncompressed data. Dies on error.
	81
	82	=back
	83
	84	=head1 SEE ALSO
	85
	86	Brotli Compressed Data Format Internet-Draft:
	87	L<https://www.ietf.org/id/draft-alakuijala-brotli-08.txt>
	88
	89	Brotli source code: L<https://github.com/google/brotli/>
	90
	91	=head1 AUTHOR
	92
	93	Marius Gavrilescu, E<lt>marius@ieval.roE<gt>
	94
4c5aa4f8 MG	95	The encoder bindings, modernisation of the decoder bindings and a
	96	clean up of the overall project were contributed by:
	97
	98	=over
	99
	100	=item Quim Rovira, E<lt>quim@rovira.catE<gt>
	101
	102	=item Ævar Arnfjörð Bjarmason, E<lt>avarab@gmail.comE<gt>
	103
	104	=item Marcell Szathmári
	105
	106	=item Mattia Barbon, E<lt>mattia@barbon.orgE<gt>
	107
390e0fef MG	108	=back
390e0fef MG	109
f9995f31 MG	110	=head1 COPYRIGHT AND LICENSE
f9995f31 MG	111
7d7bc208	112	Copyright (C) 2015-2017 by Marius Gavrilescu
f9995f31 MG	113
	114	This library is free software; you can redistribute it and/or modify
	115	it under the same terms as Perl itself, either Perl version 5.20.2 or,
	116	at your option, any later version of Perl 5 you may have available.
	117
	118
	119	=cut