##################################
cmakepp_lang/exceptions/exceptions
##################################

.. module:: cmakepp_lang/exceptions/exceptions

   Defines the public API for CMakePPLang exception handling.
   


.. function:: cpp_catch()

   Declares an exception handler function
   
   This command enables users to declare a handler function for specified
   exception types. Subsequent calls to the ``cpp_raise`` command for those
   exception types will call the handler function declared for that type.
   
   :param \*args: The exception types to declare handlers for.
   :returns: each arg will be set to the mangled name of the declared
             exception handler for that exception type.
   :rtype: desc
   
   Example Usage
   =============
   
   .. code-block:: cmake
   
      cpp_catch(my_exec_type_1 my_exec_type_2)
      function("${my_exec_type_1}" message)
         message("In my_exception_handler for exception type: my_exec_type_1")
         message("Exception details: ${message}")
      endfunction()
      function("${my_exec_type_2}" message)
         message("In my_exception_handler for exception type: my_exec_type_2")
         message("Exception details: ${message}")
      endfunction()
   
   Error Checking
   ==============
   
   If CMakePP is run in debug mode (and only if it is run in debug mode) this
   function will assert that it was called with one or more desc arguments.
   
   :var CMAKEPP_LANG_DEBUG_MODE: Used to determine if CMakePP is being run in
                                 debug mode or not.
   :vartype CMAKEPP_LANG_DEBUG_MODE: bool
   


.. function:: cpp_raise(exce_type)

   Raises an exception.
   
   This command raises an exception of the specified type. This will call
   the exception handler for that type if it is declared.
   
   :param exec_type: The exception type to be raised
   :type exec_type: desc
   :param exec_message: The exception message
   :type exec_message: optional desc
   
   Example Usage
   =============
   
   .. code-block:: cmake
   
      cpp_raise(my_exec_type)
   
   An exception message may be optionally added via calling with additonal parameters.
   
   .. code-block:: cmake
   
      cpp_raise(my_exec_type "My exception message")
   
   Error Checking
   ==============
   
   If CMakePP is run in debug mode (and only if it is run in debug mode) this
   function will assert that it was called with at least one argument and that
   the argument is of type desc.
   
   :var CMAKEPP_LANG_DEBUG_MODE: Used to determine if CMakePP is being run in
                                 debug mode or not.
   :vartype CMAKEPP_LANG_DEBUG_MODE: bool
   


.. function:: cpp_try()


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

   Denotes that we are starting a try block.
   
   This function is a no-op that completes the fencing associated with a try
   block.
   
   Error Checking
   ==============
   
   None. This function is a no-op and has no errors to check for.
   


.. function:: cpp_end_try_catch()

   Ends a try-catch block
   
   This command ends a try-catch block and removes the exception handlers for the
   specified types.
   
   :param \*args: The exception types to declare handlers for.
   
   :var CMAKEPP_LANG_DEBUG_MODE: Used to determine if CMakePP is being run in
                                 debug mode or not.
   :vartype CMAKEPP_LANG_DEBUG_MODE: bool
   
   Example Usage
   =============
   
   .. code-block::
   
      cpp_end_try_catch(my_exce_type)
   
   Error Checking
   ==============
   
   If CMakePP is run in debug mode (and only if it is run in debug mode) this
   function will assert that it was called with one or more desc arguments.