1**********************************************************************
2* Author  : Brian Maher <maherb at brimworks dot com>
3* Library : lua_zlib - Lua 5.1 interface to zlib
4*
5* The MIT License
6*
7* Copyright (c) 2009 Brian Maher
8*
9* Permission is hereby granted, free of charge, to any person obtaining a copy
10* of this software and associated documentation files (the "Software"), to deal
11* in the Software without restriction, including without limitation the rights
12* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13* copies of the Software, and to permit persons to whom the Software is
14* furnished to do so, subject to the following conditions:
15*
16* The above copyright notice and this permission notice shall be included in
17* all copies or substantial portions of the Software.
18*
19* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
25* THE SOFTWARE.
26**********************************************************************
27
28To use this library, you need zlib, get it here:
29     http://www.gzip.org/zlib/
30
31To build this library, you can use CMake and get it here:
32    http://www.cmake.org/cmake/resources/software.html
33
34...or you can use GNU Make.
35   make <platform>
36
37Loading the library:
38
39    If you built the library as a loadable package
40        [local] zlib = require 'zlib'
41
42    If you compiled the package statically into your application, call
43    the function "luaopen_zlib(L)". It will create a table with the zlib
44    functions and leave it on the stack.
45
46-- zlib functions --
47
48int major, int minor, int patch = zlib.version()
49
50    returns numeric zlib version for the major, minor, and patch
51    levels of the version dynamically linked in.
52
53function stream = zlib.deflate([ int compression_level ], [ int window_size ])
54
55    If no compression_level is provided uses Z_DEFAULT_COMPRESSION (6),
56    compression level is a number from 1-9 where zlib.BEST_SPEED is 1
57    and zlib.BEST_COMPRESSION is 9.
58
59    Returns a "stream" function that compresses (or deflates) all
60    strings passed in.  Specifically, use it as such:
61
62    string deflated, bool eof, int bytes_in, int bytes_out =
63            stream(string input [, 'sync' | 'full' | 'finish'])
64
65        Takes input and deflates and returns a portion of it,
66        optionally forcing a flush.
67
68        A 'sync' flush will force all pending output to be flushed to
69        the return value and the output is aligned on a byte boundary,
70        so that the decompressor can get all input data available so
71        far.  Flushing may degrade compression for some compression
72        algorithms and so it should be used only when necessary.
73
74        A 'full' flush will flush all output as with 'sync', and the
75        compression state is reset so that decompression can restart
76        from this point if previous compressed data has been damaged
77        or if random access is desired. Using Z_FULL_FLUSH too often
78        can seriously degrade the compression.
79
80        A 'finish' flush will force all pending output to be processed
81        and results in the stream become unusable.  Any future
82        attempts to print anything other than the empty string will
83        result in an error that begins with IllegalState.
84
85        The eof result is true if 'finish' was specified, otherwise
86        it is false.
87
88        The bytes_in is how many bytes of input have been passed to
89        stream, and bytes_out is the number of bytes returned in
90        deflated string chunks.
91
92function stream = zlib.inflate([int windowBits])
93
94    Returns a "stream" function that decompresses (or inflates) all
95    strings passed in.  Optionally specify a windowBits argument
96    that is passed to inflateInit2(), see zlib.h for details about
97    this argument.  By default, gzip header detection is done, and
98    the max window size is used.
99
100    The "stream" function should be used as such:
101
102    string inflated, bool eof, int bytes_in, int bytes_out =
103            stream(string input)
104
105        Takes input and inflates and returns a portion of it.  If it
106        detects the end of a deflation stream, then total will be the
107        total number of bytes read from input and all future calls to
108        stream() with a non empty string will result in an error that
109        begins with IllegalState.
110
111        No flush options are provided since the maximal amount of
112        input is always processed.
113
114        eof will be true when the input string is determined to be at
115        the "end of the file".
116
117        The bytes_in is how many bytes of input have been passed to
118        stream, and bytes_out is the number of bytes returned in
119        inflated string chunks.
120
121
122function compute_checksum = zlib.adler32()
123function compute_checksum = zlib.crc32()
124
125    Create a new checksum computation function using either the
126    adler32 or crc32 algorithms.  This resulting function should be
127    used as such:
128
129    int checksum = compute_checksum(string input |
130                                    function compute_checksum)
131
132        The compute_checksum function takes as input either a string
133        that is logically getting appended to or another
134        compute_checksum function that is logically getting appended.
135        The result is the updated checksum.
136
137        For example, these uses will all result in the same checksum:
138
139            -- All in one call:
140            local csum = zlib.crc32()("one two")
141
142            -- Multiple calls:
143            local compute = zlib.crc32()
144            compute("one")
145            assert(csum == compute(" two"))
146
147            -- Multiple compute_checksums joined:
148            local compute1, compute2 = zlib.crc32(), zlib.crc32()
149            compute1("one")
150            compute2(" two")
151            assert(csum == compute1(compute2))
152