Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rewrite README as markdown #22

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 26 additions & 0 deletions LICENCE
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
**********************************************************************
* Author : Brian Maher <maherb at brimworks dot com>
* Library : lua_zlib - Lua 5.1 interface to zlib
*
* The MIT License
*
* Copyright (c) 2009 Brian Maher
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
**********************************************************************
151 changes: 0 additions & 151 deletions README

This file was deleted.

156 changes: 156 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,156 @@
# Usage

## Requirements

To use this library, you need zlib, get it [here](http://www.gzip.org/zlib/) or from distribution packages.


## Installation

### From package

- debian/ubuntu: `lua-zlib`

### With luarocks/moonrock

```shell
luarocks install --server=http://rocks.moonscript.org lua-zlib
```
or
```shell
moonrocks install lua-zlib
```

# Documentation

Loading the library:

If you built the library as a loadable package

```lua
[local] zlib = require 'zlib'
```

If you compiled the package statically into your application, call
the function `luaopen_zlib(L)`. It will create a table with the zlib
functions and leave it on the stack.

```lua
-- zlib functions --

int major, int minor, int patch = zlib.version()
```

returns numeric zlib version for the major, minor, and patch
levels of the version dynamically linked in.

```lua
function stream = zlib.deflate([ int compression_level ], [ int window_size ])
```

If no `compression_level` is provided uses `Z_DEFAULT_COMPRESSION (6)`,
compression level is a number from 1-9 where `zlib.BEST_SPEED` is 1
and `zlib.BEST_COMPRESSION` is 9.

Returns a "stream" function that compresses (or deflates) all
strings passed in. Specifically, use it as such:

```lua
string deflated, bool eof, int bytes_in, int bytes_out =
stream(string input [, 'sync' | 'full' | 'finish'])
```

Takes input and deflates and returns a portion of it,
optionally forcing a flush.

A 'sync' flush will force all pending output to be flushed to
the return value and the output is aligned on a byte boundary,
so that the decompressor can get all input data available so
far. Flushing may degrade compression for some compression
algorithms and so it should be used only when necessary.

A 'full' flush will flush all output as with 'sync', and the
compression state is reset so that decompression can restart
from this point if previous compressed data has been damaged
or if random access is desired. Using `Z_FULL_FLUSH` too often
can seriously degrade the compression.

A 'finish' flush will force all pending output to be processed
and results in the stream become unusable. Any future
attempts to print anything other than the empty string will
result in an error that begins with `IllegalState`.

The eof result is true if 'finish' was specified, otherwise
it is false.

The `bytes_in` is how many bytes of input have been passed to
stream, and `bytes_out` is the number of bytes returned in
deflated string chunks.

```lua
function stream = zlib.inflate([int windowBits])
```

Returns a "stream" function that decompresses (or inflates) all
strings passed in. Optionally specify a windowBits argument
that is passed to `inflateInit2()`, see `zlib.h` for details about
this argument. By default, gzip header detection is done, and
the max window size is used.

The "stream" function should be used as such:

```lua
string inflated, bool eof, int bytes_in, int bytes_out = stream(string input)
```

Takes input and inflates and returns a portion of it. If it
detects the end of a deflation stream, then total will be the
total number of bytes read from input and all future calls to
stream() with a non empty string will result in an error that
begins with IllegalState.

No flush options are provided since the maximal amount of
input is always processed.

eof will be true when the input string is determined to be at
the "end of the file".

The `bytes_in` is how many bytes of input have been passed to
stream, and `bytes_out` is the number of bytes returned in
inflated string chunks.

```lua
function compute_checksum = zlib.adler32()
function compute_checksum = zlib.crc32()
```

Create a new checksum computation function using either the
adler32 or crc32 algorithms. This resulting function should be
used as such:

```lua
int checksum = compute_checksum(string input | function compute_checksum)
```

The `compute_checksum` function takes as input either a string
that is logically getting appended to or another
`compute_checksum` function that is logically getting appended.
The result is the updated checksum.

For example, these uses will all result in the same checksum:

```lua
-- All in one call:
local csum = zlib.crc32()("one two")

-- Multiple calls:
local compute = zlib.crc32()
compute("one")
assert(csum == compute(" two"))

-- Multiple compute_checksums joined:
local compute1, compute2 = zlib.crc32(), zlib.crc32()
compute1("one")
compute2(" two")
assert(csum == compute1(compute2))
```