Permalink
Browse files

Documentation improved.

  • Loading branch information...
1 parent f4e5d75 commit 226a370f695f40bb61cb7982a2a2541f2032d7e0 @egorich239 committed Aug 3, 2010
Showing with 80 additions and 1 deletion.
  1. +1 −1 README
  2. +79 −0 doc/index.txt
View
2 README
@@ -29,5 +29,5 @@ Build puts the compress-bindings.node binary module in build/default.
Usage examples
--------------
-See demo/async-test.js.
+See demo/demo.js.
View
@@ -0,0 +1,79 @@
+node-compress is asynchronous compression/decompression library. Library
+provides two different APIs: callback based, and streams events based.
+The latter is actually a wrapper around the first.
+
+Callback API
+------------
+Several classes are contained in the package: Gzip, Gunzip, Bzip, Bunzip.
+They have pretty strict limitations on data input/output format, share same
+interface and use callbacks.
+All callbacks have following call convention: callback(exc, binary_string).
+Here:
+ exc is exception if any occured while processing request;
+ binary_string is binary-encoded output.
+Those functions having input always obtain NodeJS Buffer instance.
+
+All (de)compressor object might be used for processing exactly one
+stream. They are initialized at construction time, all data are passed to
+(de)compressor by consequent calls of write() method. Use close() method to
+finalize input stream and obtain the final part of output stream.
+destroy() method might be used at any moment to stop all the processing
+immediately and avoid finalizing stream. Note, that close() is NOT called
+automatically when (de)compressor object is garbage collected.
+
+Library methods throw exceptions in several cases. This is done intentionally as
+usually means programming error.
+
+1. write(buffer[, opt_callback])
+ Push buffer to input stream. Asynchronously call opt_callback for output if
+ any specified. Callback is warranted to be called at at least next NodeJS
+ tick.
+
+ Exceptions:
+ TypeError if buffer is not of type Buffer, or callback is not a function.
+
+2. close([opt_callback])
+ Finalize input, and flush output buffers. Asynchronously call opt_callback if
+ any specified. Callback is warranted to be called at at least next NodeJS
+ tick.
+
+ Exceptions:
+ TypeError if callback is not a function.
+
+3. destroy()
+ Avoid finalizing stream and clean internal structures.
+
+Callback API constructors
+-------------------------
+Gzip(compressionLevel)
+ 1 <= compressionLevel <= 9
+
+Gunzip()
+
+Bzip(blockSize, workFactor)
+ See bzip library documentation for details.
+
+Bunzip()
+
+
+Streams API
+-----------
+This is a wrapper around callback API: GzipStream, GunzipStream, BzipStream,
+BunzipStream. These are read-write streams mostly conformant with standard
+NodeJS streaming API (as of NodeJS version 0.1.102) with one exception which
+happened for historical reasons and is likely to disappear in future: stream has
+default input encoding, so write(data) with no encoding specified interprets
+data as if they are encoded with default encoding set by setInputEncoding(enc).
+As of version v0.1.8 warning is output to console when setInputEncooding is
+used. This warning might be avoided by calling module-global method
+setApiWarnings(false).
+
+Streams API constructors
+------------------------
+All the constructors mirror arguments of counter-part (de)compressor.
+
+
+Adding more compressors
+-----------------------
+I'm really tired to write so many letters, so take a look at examples:
+src/bzip.cc, src/gzip.cc. Send emails for details: egorich.3.04@gmail.com.

0 comments on commit 226a370

Please sign in to comment.