Improvements and fixes

.gitignore

@@ -9,3 +9,5 @@
 
 *.o
 *.so
+
+build/

AUTHORS

@@ -0,0 +1,11 @@
+ORIGINAL AUTHORS
+---
+This library was written by Salvatore Sanfilippo for Redis, but is maintained as a separated project by the author.
+
+CONTRIBUTORS
+---
+Fabrício Puppi (http://github.com/puppi)
+
+ADDITIONAL CREDITS
+---
+Some of the test vectors in "test.lua" are obtained from the Javascript MessagePack-JS library (https://github.com/cuzic/MessagePack-JS).

COPYING

@@ -0,0 +1,20 @@
+Copyright (C) 2012 Salvatore Sanfilippo.  All rights reserved.
+
+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.

NEWS

@@ -0,0 +1,4 @@
+20-Feb-2012 (ver 0.3.0): Module renamed lua-cmsgpack (was lua-msgpack).
+20-Feb-2012 (ver 0.2.1): Minor bug fixing.
+20-Feb-2012 (ver 0.2.0): Tables encoding improved.
+19-Feb-2012 (ver 0.1.0): Initial release.

README → README.md

@@ -1,46 +1,63 @@
-README for lua_cmsgpack.c
+lua-cmsgpack
 ===
 
 Lua-cmsgpack is a MessagePack (http://msgpack.org) implementation and bindings for
-Lua 5.1 in a self contained C file without external dependencies.
+Lua 5.1 in C without external dependencies.
 
 This library is open source software licensed under the BSD two-clause license.
 The library is currently considered in BETA STAGE for lack of extensive testing.
 
+
+
 INSTALLATION
 ---
-
 Using LuaRocks (http://luarocks.org):
 
-* Install current stable release:
+* Install current stable release
 
-    sudo luarocks install lua-cmsgpack
+    $ sudo luarocks install lua-cmsgpack
 
-* Install current Git master head from GitHub:
+* Install current Git master head from GitHub
 
-    sudo luarocks install lua-cmsgpack --from=rocks-cvs
+    $ sudo luarocks install lua-cmsgpack --from=rocks-cvs
 
 * Install from current working copy
 
-    cd lua-cmsgpack/
-    sudo luarocks make rockspec/lua-cmsgpack-scm-1.rockspec
+    $ cd lua-cmsgpack/
+    $ sudo luarocks make rockspec/lua-cmsgpack-scm-1.rockspec
 
 If you embed Lua and all modules into your C project, just add the
 lua_cmsgpack.c file and call the following function after creating the Lua
 interpreter:
 
     luaopen_cmsgpack(L);
 
+
+Note that this function should be called as a Lua function, and not directly.
+It will return the module namespace and register it in the global environment
+under the key "cmsgpack".
+
+
+
 USAGE
 ---
+    cmsgpack = require 'cmsgpack'
 
 The exported API is very simple, consisting in two functions:
 
-* msgpack = cmsgpack.pack(lua_object)
-* lua_object = cmsgpack.unpack(msgpack)
+    msgpack = cmsgpack.pack(lua_object1, lua_object2, ...)
+    lua_object1, lua_object2, ... = cmsgpack.unpack(msgpack)
 
-However because of the nature of Lua numerical and table type a few behavior
-of the library must be well understood to avoid problems:
+
+cmsgpack.pack receives 0 or more Lua values and converts them into a stream in the MessagePack protocol.
+If a value can't be converted (userdata, for instance), it is mapped to nil. The function doesn't throw
+errors.
+
+cmsgpack.unpack receives a string representing a MessagePack stream and returns all unpacked objects.
+If the string is invalid, an error is thrown.
+
+Because of the nature of Lua table, which can represent either a numerical or associative array, the
+following principle is adopted:
 
 * A table is converted into a MessagePack array type only if *all* the keys are
 composed of incrementing integers starting at 1 end ending at N, without holes,
@@ -51,6 +68,8 @@ maps.
 * When a Lua number is converted to float or double, the former is preferred if there is no loss of precision compared to the double representation.
 * When a MessagePack big integer (64 bit) is converted to a Lua number it is possible that the resulting number will not represent the original number but just an approximation. This is unavoidable because the Lua numerical type is usually a double precision floating point type.
 
+
+
 NESTED TABLES
 ---
 Nested tables are handled correctly up to LUACMSGPACK_MAX_NESTING levels of
@@ -61,16 +80,15 @@ as MessagePack nil value.
 It is worth to note that in Lua it is possible to create tables that mutually
 refer to each other, creating a cycle. For example:
 
-a = {x=nil,y=5}
-b = {x=a}
-a['x'] = b
+    a = { x = nil, y = 5 }
+    b = { x = a }
+    a['x'] = b
 
 This condition will simply make the encoder reach the max level of nesting,
 thus avoiding an infinite loop.
 
-CREDITS
----
 
-This library was written by Salvatore Sanfilippo for Redis, but is maintained as a separated project by the author.
 
-Some of the test vectors in "test.lua" are obtained from the Javascript MessagePack-JS library (https://github.com/cuzic/MessagePack-JS).
+COPYRIGHT AND CREDITS
+---
+See COPYING and AUTHORS.