--[[----------------------------------------------------------------------------

blonde.lua

--------------------------------------------------------------------------------

ADOBE CONFIDENTIAL
------------------
Copyright 2012 Adobe Systems Incorporated
All Rights Reserved.

NOTICE: All information contained herein is, and remain the property of
Adobe Systems Incorporated and its suppliers, if any. The intellectual and
technical concepts contained herein are proprietary to Adobe Systems
Incorporated and its suppliers and may be covered by U.S. and Foreign
Patents, patents in process, and are protected by trade secret or copyright
law.  Dissemination of this information or reproduction of this material is
strictly forbidden unless prior written permission is obtained from
Adobe Systems Incorporated.

----------------------------------------------------------------------------]]--

-- @mark blonde namespace

--[[!
	\class blonde
	\brief 	BLONDE (Binary Lua Object Notation for Data Exchange) defines a terse binary
	data protocol for encoding and decoding Lua values. It is intended for use as a transit
	format both within a process and across processes.

	WARNING: When using BLONDE byte streams in C language, you must be careful
	to use the length provided by lua_objlen() and not the length computed by
	strlen(). The binary encoding does not use the zero byte as a terminator.

	A BLONDE bytestream represents any number of Lua values, of the standard Lua
	types nil, boolean, number, string, or table. You can create custom encoders to
	support additional types.
	
	Tables can be nested up to a reasonable depth (to guard against infinite recursion).
	A table can contain any of the supported data types as keys and values.
        The protocol does not support referencing the same
        value multiple times within a table. When encoding, the library does not check
	for this condition; it re-encodes a value as many times as it appears.
	
--]]

--==============================================================================

local blonde = {}

--[[!

	\brief Converts one or more Lua values into a BLONDE byte stream (a string).
	The result is encoded as a BLONDE_TUPLE if there are multiple values.

	\param value  A Lua value encode.
	\param ... Additional Lua values to encode.
	\return A string that is a BLONDE-encoded representation of value, ...

--]]
function blonde.encode( --[[valueOrType]] value, ... )
	-- This function is implemented natively in blonde_encode_L.
end
	
--------------------------------------------------------------------------------

--[[!

	\brief Converts one or more Lua values into a BLONDE byte stream (a string).
	The result is encoded as a BLONDE_TUPLE if there are multiple values.
	This version is slightly slower	because it sorts the keys
	 when enumerating tables.

	\param value  A Lua value encode.
	\param ... Additional Lua values to encode.
	\return A string that is a BLONDE-encoded representation of value, ...

--]]
function blonde.encode_stable_output( --[[valueOrType]] value, ... )
	-- This function is implemented natively in blonde_encode_stable_output_L.
end
	
--------------------------------------------------------------------------------

--[[!

	\brief Decodes a BLONDE-encoded byte stream to the
		corresponding Lua values.

	\param encoded The BLONDE-encoded string
	\return The Lua value or values that were originally encoded.

--]]
function blonde.decode( --[[string]] encoded )
	-- This function is implemented natively in blonde_decode_L.
end

--==============================================================================

-- BLONDE is implemented natively -- the previous value of the local blonde
-- was for documentation purposes.
blonde = require "blondeImp"

return blonde
