Go: [API change] Abstract away from a document body compressor

Sereal version 3 introduced a new document type "3": compressed Sereal
format, using zlib compression. Hence we've got two different ways to
compress the same Sereal document body.

In order to unify the encoder interface and simplify adding a new zlib
document format, I am decoupling a compression mechanism.

Sadly it breaks the public API of the package. On the bright side the
change helps to make potential further extensions easier and more
seamless, and keep the API cleaner.

Also according to go-search.org[1] there is only a single package
"github.com/alecthomas/go_serialization_benchmarks" that depends on ours
and it yet does not use the changed API. So we are good (-:

Consider --ignore-all-space to view the diff.

[1] http://go-search.org/view?id=github.com%2fSereal%2fSereal%2fGo%2fsereal
Go: Do not set document type in compressor

Compressor is supposed to know nothing about a document header and
should work with a raw payload only. This commit is the first step
toward the goal.
Go: Rename serealSnappyLength --> serealSnappyIncremental

It's called SRL_PROTOCOL_ENCODING_SNAPPY_INCREMENTAL in the reference
Perl implementation. Renaming to make it more conformant.
Go: Prefere a document type constant over a bare number
Go: Write two basic encoder benchmarks

Benchmark encoding a complex nested data structure with a user header
into raw and Snappy Sereal documents.
Tests: Allow to compress a test corpus

I wanted to run roundtrip tests against a compressed corpus, but
Sereal::TestSet allowed to specify only a protocol version.

This change enables one to specify an optional compression via
$Sereal::TestSet::COMPRESS. By default the corpus is not compressed.
See the compress attribute in Sereal::Encode for available options.
Go: Allow to run compat tests against a compressed corpus

On command line one can pass make(1) a CORPUS_COMPRESS variable to
enable compression of a testing corpus. For instance:

    $ make compat CORPUS_COMPRESS=SRL_SNAPPY

See the compress attribute in Sereal::Encode for available compression
algorithms.

Rent. I wanted to split up a long command line in the test_dir recipe
into multiple lines, but, sigh, it's impossible:

> Sometimes you want to split a long line inside of single quotes, but you
> don't want the backslash/newline to appear in the quoted content. This
> is often the case when passing scripts to languages such as Perl, where
> extraneous backslashes inside the script can change its meaning or even
> be a syntax error.
--- https://www.gnu.org/software/make/manual/make.html#Splitting-Recipe-Lines
Go: Make compressor work with opaque data; refactor MarshalWithHeader()

This is a follow up on 16cad24. Compressor is supposed to know nothing
about a document header and should work with a raw payload only. This
commit is the first step toward the goal.

Now a compressor takes an opaque blob of data, compresses, and
returns it back.

As a side change I renamed variables b and encoded; and explicitly
separated encoded document header, optional header suffix, and body.

Concatination of encoded header and body is done in a suboptimal way,
but I plan to improve it later on.
Go: Don't make an empty slice

Following the @dgryski's advice.
Go: Concat encoded header and body in one go

Follow up on my e2987ba and @dgryski's remark.
Go: Move SnappyCompressor into its own file

Purely a cosmetic change to follow up on ce45bf3079 and keep diffs
cleaner. Zlib support is upcoming, hence it makes sense to tidy up a bit
and avoid pile up everything in encode.go.
Go: Document type must be always set

Code that sets document type resided under the if-condition and was
invoked only when a compression was set. That's wrong. It all worked
only because default values were the same as expected.

Also no need to await for a compressed payload---doctype may be set at
once.
Go: Do not re-build a test corpus if a requested compression didn't change

It fixes an oversight I made in bc6eb1e to avoid redundant corpus
generaton in spirit of 698bf3e.
Go: Decouple document decoder and body decompressor

In the spirit of ce45bf30795 abstract away from a body compressor. This
change simplifies introduction of zlib support.
Go: Add support of zlib document compression

Sereal protocol version 3 introduced the new document type 3, the zlib
compression. This commit implements zlib support for both encoder and
decoder via the ZlibCompressor type.

Compat tests pass:

    (1) mvuets@ilosonaloje:~/proj/sereal/Go/sereal$ make test_all CORPUS_PROTO_VER=3 CORPUS_COMPRESS=SRL_ZLIB
    rm -f test_dir/VERSION_*
    rm -f test_dir/COMPRESS_*
    perl -Mblib=../../Perl/Decoder/blib/ -Mblib=../../Perl/Encoder/blib -I../../Perl/shared/t/lib/ -MSereal::TestSet -MSereal::Encoder -e '$Sereal::TestSet::PROTO_VERSION=3; $Sereal::TestSet::COMPRESS=Sereal::Encoder::SRL_ZLIB; Sereal::TestSet::write_test_files("test_dir")'
    touch "test_dir/VERSION_3"
    touch "test_dir/COMPRESS_SRL_ZLIB"
    go test
    PASS
    ok      github.com/Sereal/Sereal/Go/sereal      0.051s
    rm -f test_dir/test_data_*-go.out
    go test -test.run=TestCorpus
    PASS
    ok      github.com/Sereal/Sereal/Go/sereal      0.038s
    prove ./test-compat.pl
    ./test-compat.pl .. ok
    All tests successful.
    Files=1, Tests=714,  0 wallclock secs ( 0.08 usr  0.00 sys +  0.16 cusr  0.02 csys =  0.26 CPU)
    Result: PASS
Go: Refine README.md
Go: Document exported Snappy and Zlib compressors
Go: Add support for obsolete document type 1 (non-incr Snappy)

Document type 1 (non-incremental Snappy) has been obsoleted since Sereal
protocol version 2. But the package allows to create documents of
version 1, hence it should be possible to use document type 1 as well.

The compat test suite isn't able to generate a corpus of version 1 and
document type 1. The following little patch may be applied in order to
generate such a corpus:

    diff --git a/Perl/shared/t/lib/Sereal/TestSet.pm b/Perl/shared/t/lib/Sereal/TestSet.pm
    index 2608baf..687a23f 100644
    --- a/Perl/shared/t/lib/Sereal/TestSet.pm
    +++ b/Perl/shared/t/lib/Sereal/TestSet.pm
    @@ -882,8 +882,8 @@ sub write_test_files {
         }

         my $encoder = Sereal::Encoder->new({
    -        protocol_version => $PROTO_VERSION,
    -        compress => $COMPRESS || Sereal::Encoder::SRL_UNCOMPRESSED(),
    +        protocol_version => 1,
    +        snappy => 1,
         });
         foreach my $i (0..$#RoundtripTests) {
             my $testno = @BasicTests + $i + 1;

And tests pass:

    (1) mvuets@ilosonaloje:~/proj/sereal/Go/sereal$ rm -rf test_dir
    (1) mvuets@ilosonaloje:~/proj/sereal/Go/sereal$ make test_all
    rm -f test_dir/VERSION_*
    rm -f test_dir/COMPRESS_*
    perl -Mblib=../../Perl/Decoder/blib/ -Mblib=../../Perl/Encoder/blib -I../../Perl/shared/t/lib/ -MSereal::TestSet -MSereal::Encoder -e '$Sereal::TestSet::PROTO_VERSION=3; $Sereal::TestSet::COMPRESS=Sereal::Encoder::SRL_UNCOMPRESSED; Sereal::TestSet::write_test_files("test_dir")'
    touch "test_dir/VERSION_3"
    touch "test_dir/COMPRESS_SRL_UNCOMPRESSED"
    go test
    PASS
    ok      github.com/Sereal/Sereal/Go/sereal      0.070s
    rm -f test_dir/test_data_*-go.out
    go test -test.run=TestCorpus
    PASS
    ok      github.com/Sereal/Sereal/Go/sereal      0.072s
    prove ./test-compat.pl
    ./test-compat.pl .. ok
Go: Copy "compress/zlib" compression level constants

Copy "compress/zlib" compression level constants here, so that a
user of the "github.com/Sereal/Sereal/Go/sereal" package doesn't have to
also import "compress/zlib".
Go: Add Zlib-compressed encoding benchmark

Benchmark encoding a complex nested data structure with a user header
into a Zlib-compressed Sereal document.