########################
cmakepp_lang/object/call
########################

.. module:: cmakepp_lang/object/call

   Defines functions used to process calls to member functions assigned to an
   object.
   


.. function:: _cpp_object_call_guts(this result method)

   Determines the correct member function to call for the input.
   
   This function is factored out of ``_cpp_object_call`` to avoid contaminating
   the caller's namespace with temporary variables needed to lookup the symbol of
   the member function we are calling.
   
   :param this: The Object instance whose member function is being called.
   :type this: obj
   :param result: Identifier to hold the symbol of the function to call.
   :type result: desc
   :param method: The name of the method to call. The actual name is
                  case-insensitive.
   :type method: desc
   :param \*args: The arguments which are being forwarded to the member function.
   :returns: ``result`` will be set to the symbol (mangled name) of the
             member function to call.
   :rtype: fxn
   
   .. note::
   
      This function is considered an implementation detail of
      ``object_call`` and does not perform any type checking.
   
   Error Checking
   ==============
   
   This function will raise an error if the Object instance does not contain a
   member function capable of being called with the provided signature.
   


.. function:: _cpp_object_call(this method)


   .. note:: This is a macro, and so does not introduce a new scope.

   Calls the specified member function.
   
   This is the "public" API (users of CMakePP should rarely need to go through
   the Object class directly) for calling an Object instance's member function.
   This function encapsulates the process of determining the correct overload to
   call and actually invoking it.
   
   :param this: The Object instance whose member function is being called.
   :type this: obj
   :param method: The name of the member function to call.
   :type method: desc
   :param \*args: The arguments to forward to the member function (the required
                  first argument of the ``this`` pointer is forwarded
                  automatically and should not be provided in this list)
   :returns: This function will return whatever the member function returns
             using the mechanism of that function. If the member function does
             not return this function will not return.
   :rtype: str
   
   :var CMAKEPP_LANG_DEBUG_MODE: Used to determine if CMakePP is being run in
                                debug mode or not.
   :vartype CMAKEPP_LANG_DEBUG_MODE: bool
   
   .. note::
   
      This command is a macro to avoid needing to forward the results of the
      subcall.
   
   Error Checking
   ==============
   
   If CMakePP is run in debug mode (and only if CMakePP is run in debug mode)
   this function will ensure that it was called with the correct number and types
   of arguments. If it is not an error will be raised.
   
   Additionally, this function will raise an error if the Object instance does
   not contain a suitable overload for the provided arguments.