.. include:: ../global.rst

Raising Conditions
------------------

You can raise conditions in user-code.

You can raise standard :lname:`Idio` errors with :ref:`error <error>`
for a generic :ref:`^idio-error <^idio-error>` or :ref:`error/type
<error/type>` for a more specific condition type.

You can raise a specific condition with :ref:`raise <raise>` which
supports any kind of condition type, including user-defined ones.

Finally, :ref:`reraise <reraise>` supports a niche problem where you
recognise that, as a handler potentially several layers down in the
trap-handling stack, you are raising a new condition for which the
user might have defined a handler some layers above where you are now.
What ``reraise`` does is look for the highest numbered trap-handler on
the stack and start (again) with it.


.. _`error`:

.. idio:function:: error loc msg [detail]


   raise an ^idio-error				
   						
   :param loc: function name			
   :type loc: symbol				
   :param msg: error message			
   :type loc: string				
   :param detail: detailed arguments, defaults to ``#n``	
   :type detail: list, optional			
   						
   This does not return!				


.. _`error/type`:

.. idio:function:: error/type ct loc msg [detail [...]]


   raise a `ct` condition				
   						
   :param ct: condition type			
   :type ct: condition type			
   :param loc: function name			
   :type loc: symbol				
   :param msg: error message			
   :type loc: string				
   :param detail: detailed arguments, defaults to ``#n``	
   :type detail: list, optional			
   						
   This does not return!				

   :Example:
   
   Suppose you want to validate what should be a string argument for a
   minimum length:
   
   .. code-block:: idio
   
      define (frob-string str) {
        (or (string? s)
            (error/type ^rt-parameter-type-error 'frob-string "not a string" s))
        (or ((string-length s) gt 10)
            (error/type ^rt-parameter-value-error 'frob-string "string should be > 10 code points" s))
        ...
      }
   
      frob-string #t       ; ^rt-parameter-type-error:not a string (#t) at frob-string: detail (#t)
      frob-string "hello"  ; ^rt-parameter-value-error:string should be > 10 code points ("hello") at frob-string: detail ("hello")
   

.. _`raise`:

.. idio:function:: raise c


   raise the condition `c`					
   							
   !! MAY RETURN !!					
   							
   :param c: condition to raise				
   :type c: condition					
   							
   :return: ``#<unspec>``					


.. _`reraise`:

.. idio:function:: reraise c


   reraise the condition `c`				
   							
   In particular this rediscovers the top-most trap	
   handler.						
   							
   :param c: condition to raise				
   :type c: condition					




.. include:: ../commit.rst