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