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

WFArguments.lua

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

ADOBE CONFIDENTIAL
------------------
Copyright 2011 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.

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

	-- WF.core.utils
local WFArgumentsImp = require 'WFArgumentsImp'


--============================================================================--
--[[!
	\brief This namespace contains functions to help you verify
		that function arguments match the expected or required type.
--]]

-- @mark WFArguments namespace

local WFArguments = {}

--------------------------------------------------------------------------------
--[[!
	\brief Verifies that arguments to the calling function match expected types.
	
	Throws an error if it finds an illegal argument.
	
	\param ... (one or more strings or tables) Expected types for each function.
	
	Use one type description for each argument in the calling function to be
	verified. Type descriptions can be:
	
		- The exact name of a Lua type (such as 'string' or 'number').
		- The name of a class described by \c Rx.Class (or, more precisely,
			any table for which <code>getametatable( value ).__type == typename</code>).
		- The name of a type checker registered via \c WFArguments.registerChecker().
		- 'callable': A function or an item with a __call metamethod
		- '+string' to specify a non-empty string.
		- '_' to permit any value.
		- '!nil' to permit any value except nil.
	
	If the argument is optional, prefix the type description with '?'.
	For example, use '?string' to signal that \c nil or any string is legal.
	
	Merge type descriptions with "|" if multiple types are permitted.
	For example 'string|number' permits both types, and '?string|number'
	accepts nil, string, or number values. Spaces around
	the type names are ignored; you can use '? string | number'.
	
	If the type description is a table, the argument at that
	position must be a table and each member of the table passed to the calling
	function must match the type specification at the corresponding index in
	the table. For example:

\code
local template = { foo = 'number', baz = 'string|boolean' }

local function example( args )

	WFArguments.check( template )

end

example { valA = 42, valB = true }	-- succeed
example { valA = 42 }			-- fail (valB is not string or boolean)
example { valA = 42, valB = 45 }	-- fail (valB is not string or boolean)
\endcode

	Any other members present in the table are ignored, as long as there are
	members that satisfy the specified conditions.
	
	The keys of the template table must be strings. If the keys are not strings,
	their values cannot be verified.
--]]

--: public: static void check( ... );

WFArguments.check = WFArgumentsImp.check

--------------------------------------------------------------------------------
--[[!
	\brief Verifies that members of a table match expected types.
	
	Throws an error if it finds an illegal table member.
	
	\param template (table) Expected types for each member
		(See description under \c WFArguments.check for syntax.)
	\param value (table) Table value to verify
--]]

--: public: static void checkTable( table template, table value );

WFArguments.checkTable = WFArgumentsImp.checkTable

--------------------------------------------------------------------------------
--[[!
	\brief Registers a custom type checker for use in future calls to
		\c WFArguments.check.
	
	\param name (string) The name for the type checker.
		It is an error to reuse the same name for a checker in the same thread
		unless you call \c WFArguments.unregisterChecker in the interim.
	\param checker (function|table)	 The type-checker function or table.
		If a function, it must take one argument and return
		\c true if the argument is valid, or \c false if not.
		(The calling code converts this into an error.)
	
	\todo What does a table mean here?
	
	\see WFArguments_uuid for an example of a custom type checker
 	
--]]

--: public: static void registerChecker( string name, function or table checker );

WFArguments.registerChecker = WFArgumentsImp.registerChecker

--------------------------------------------------------------------------------
--[[!
	\brief Unregisters a previously-registered custom type checker.
 
 	Cancels a registration previously added by \c WFArguments.registerChecker,
	thus making it safe to use that name again in a subsequent call to that
	function.
	
	If no such registration previously occurred, the call has no effect.

		\param name (string) The name for the registered type checker

--]]

--: public: static void unregisterChecker( string name );

WFArguments.unregisterChecker = WFArgumentsImp.unregisterChecker

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

return WFArguments
