-- Return the value of a global packing/unpacking option.
--
-- Default Flags:
-- 'empty_table_as_array' + 'unsigned' + 'without_hole + 'double'
--
-- Options:
--  NUMBER_OPTS: See Developer Notes for how floating-point/integer types are
--  handled under the varying Lua builds/versions.
--   'float' - Encodes a lua_Number as float regardless of LUA_FLOAT_TYPE.
--   'double' - Encodes a lua_Number as double regardless of LUA_FLOAT_TYPE.
--   'integer' - Encodes a lua_Number as an integer regardless of type.
--   'unsigned' - Encode integers as unsigned values when possible, i.e., positive
--      lua_Integers are msgpacked as unsigned int; this is default for
--      lua-MessagePack.
--
--  STRINGS_OPTS: When both disabled the 'v5' spec for encoding strings is used.
--   'string_compat' - Use MessagePack 'v4' spec for encoding strings.
--   'string_binary' - Encode strings using the binary tag.
--
--  TABLE_OPTS:
--   'always_as_map' - Encode all tables as a sequence of <key, value> pairs.
--   'without_hole' - Only contiguous arrays, i.e., integer keys [1, N] all
--      contain non-nil value, are to be packed as an msgpack array type.
--   'with_hole' - Allow tables to be packed as arrays iff all keys are positive
--      integers and satisfies the MP_TABLE_CUTOFF limitation. Inserting nil's
--      when encoding to satisfy the array type.
--   'empty_table_as_array' - empty tables packed as arrays. Beware, when
--      'always_as_map' is enabled, this flag is forced to disabled.
--   'sentinel' - Replace 'nil' values with a 'sentinel' value during unpacking.
--      The packer will always replace sentinel's with null during packing.
--
--  TYPE_OPTS:
--   'ignore_invalid' - Ignore invalid types (i.e., ones without 'type' extensions)
--      during encoding by packing 'nil' (short circuiting) instead of throwing
--      an error.
--
--  COMPAT_OPTS:
--   'small_lua' - lua-MessagePack compatibility field.
--   'full64bits' - lua-MessagePack compatibility field.
--   'long_double' - lua-MessagePack compatibility field.
value = msgpack.getoption(option)

-- Set a global packing/unpacking option; see getoption.
msgpack.setoption(option, value)

-- A sentinel value used to represent an explicit "nil" value when packing or
-- (optionally) unpacking. This is implemented with a 'light userdata' in Lua5.1/LuaJIT,
-- and a 'light' C function for Lua 5.2, Lua 5.3, and Lua 5.4 (thereby allowing
-- msgpack.null == msgpack.null()). This feature has no equivalent in MessagePack.lua
null = msgpack.null -- or msgpack.sentinel

-- Receives any number of arguments and pack their values.
packedString = msgpack.pack(...)

-- pack_args(...): receives any number of arguments and packs their values as an
-- array; ensuring a subsequent table.unpack(msgpack.unpack()) can be passed
-- directly to a Lua function call with proper handling of intermediate nil
-- values.
--
-- By default tables, e.g., {...}, are packed with the 'without_hole' flag,
-- meaning arrays with nil values are to be encoded as maps. This conflicts with
-- function parameters and required sequences.
packedArray = msgpack.pack_args(...)

-- Returns a userdata that maintains a persistent msgpack packing state. The
-- userdata has the following metamethods
--
-- __len: Return the length of the current msgpack encoded string.
-- __tostring: Return the current msgpack encoded string.
-- __concat: Append another msgpack encoded strings to the packer.
-- __call, __add, __shl(>= 5.3): Encode, and append, the provided Lua values.
-- __index: Indexes functions of the form: f(packer, [, value [, ... [, value]...]])
--      Where the values are casted to the named type:
--      "nil",
--       "any",
--       "boolean", "true", "false",
--       "fix_uint8", "fix_uint16", "fix_uint32", "fix_uint64",
--       "fix_int8", "fix_int16", "fix_int32", "fix_int64",
--       "uint8", "uint16", "uint32", "uint64",
--       "int8", "int16", "int32", "int64",
--       "char", "signed_char", "unsigned_char",
--       "short", "integer", "long", "long_long",
--       "unsigned_short", "unsigned_int", "unsigned_long", "unsigned_long_long",
--       "signed_int16", "signed_int32", "signed_int64",
--       "integer", "signed", "unsigned",
--       "float", "double", "number",
--       "_string", "string_compat", "string", "binary",
--       "_table", "map", "array", "table"
--
-- @EXAMPLE:
--  ud = msgpack.new()
--  ud(1, 2, math.pi) -- Append; current state: { 1, 2, math.pi }.
--  ud .. tostring(ud) -- Duplicate; current state: { 1, 2, math.pi, 1, 2, math.pi }.
--  ud:float(4.0) -- Append; current state: { 1, 2, math.pi, 1, 2, math.pi, 4.0f }.
--  msgpack.unpack(tostring(ud)) -- Unpacks the current msgpack stream
packer = msgpack.new()

-- Unpack all elements, up to a potential limit, from a msgpack encoded string.
-- Returning the number of unpacked objects placed onto the Lua stack.
... = msgpack.unpack(encoded_string [, offset [, limit [, end_position]]])

-- MessagePack.lua ABI compatible unpack: ignore additional function arguments.
-- When compiled with LUA_MSGPACK_COMPAT, "unpack_compat" becomes the "unpack"
-- function, while "unpack" becomes "unpack2".
... = msgpack.unpack_compat(encoded_string)

-- Unpack all elements, up to a potential limit, from a msgpack encoded string.
-- Returning (1) the position in the string where the decoding ended, 0 for
-- completion; and (2) and all decoded objects (up to limit).
--
-- Iterator Example:
--      local position,element = 1,nil
--      while position ~= 0 do
--        position,element = msgpack.next(encoded_string, position, 1)
--      end
new_position,... = msgpack.next(encoded_string [, position [, limit [, end_position ]]])

-- Register an extension-type. The encoder_table parameter is often a metatable
-- with additional metamethods for serializing tables/userdata:
--
--   __ext: Unique msgpack extension identifier. Note that applications can only
--    assign 0 to 127 to store application-specific type information.
--
--   __pack: An encoder function:
--              encoding[, handled_header] = f(self, type)
--    where "type" is the extension type identifier (allowing one function
--    handling multiple encodings). The 'handled_header' result is an optional
--    field to tell the encoder that the serialization function 'f' handled
--    packing its extension header.
--
--   __unpack: A decoder function: value = f(encoded_string) that is the inverse
--    to __pack. Note, 'f' may only return one value as the custom extension
--    types may be used to encode key/values in tables/arrays.
--
-- @EXAMPLE:
--   metatable = {
--     __ext = 0x15,  -- Extension type identifier
--
--     __pack = function(self, type) -- Object Serialization
--          return msgpack.pack(self.x, self.y, self.z)
--     end,
--
--     __unpack = function(encoded, type) -- Factory
--          local x,y,z = msgpack.unpack(encoded)
--          return setmetatable({x = x, y = y, z = z}, metatable)
--     end,
--
--    --[[ Metamethods --]]
--  }
msgpack.extend(encoder_table)

-- Get the extension-type definition for encoding/decoding tables/userdata
-- definitions.
metatable = msgpack.extend_get(ext_id)

-- Explicitly remove the extension definition for all type identifiers provided
-- to this function; returning zero.
msgpack.extend_clear(ext_id1 [, ext_id2 ... [, ext_idN]])

-- Associate the name of a Lua type (see: lua_typename/type) to a encoder table,
-- and possibly a unique MessagePack extension type identifier.
--
-- @NOTE: This feature is going to be reworked.
-- @EXAMPLE:
--  m.extend("function", {
--      __ext = 42,
--
--      __pack = function(fct, t)
--          assert(type(fct) == "function", "is function")
--          return m.pack(assert(string.dump(fct), "function pack"))
--      end,
--
--      __unpack = function(s, t)
--          local str = m.unpack(s)
--          return assert(loadstring(str), "function unpack")
--      end,
--  })
--
-- @EXAMPLE:
--  m.extend("function", 42) -- '42' is an already registered extension identifier
msgpack.settype(type_string [, ext_id])

-- Get the encoder table associated to the name of a Lua type.
msgpack.gettype(type_string)

-- lua-MessagePack:
-- setoption that only processes: "string", "string_compat", "string_binary"
msgpack.set_string(string_value)
-- setoption that only processes: "without_hole", "with_hole", "always_as_map"
msgpack.set_array(array_value)
-- setoption that only processes: "signed", "unsigned"
msgpack.set_integer(integer_value)
-- setoption that only processes: "float", "double"
msgpack.set_number(number_value)