%-*-mode:latex-*-
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Copyright (C) 1996-2004 Jason Evans <jasone@canonware.com>.
% All rights reserved.
% 
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions
% are met:
% 1. Redistributions of source code must retain the above copyright
%    notice(s), this list of conditions and the following disclaimer
%    unmodified other than the allowable addition of one or more
%    copyright notices.
% 2. Redistributions in binary form must reproduce the above copyright
%    notice(s), this list of conditions and the following disclaimer in
%    the documentation and/or other materials provided with the
%    distribution.
% 
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
% EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
% IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
% PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE
% LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
% CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
% SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
% BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
% WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
% OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
% EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% Version: Onyx 5.1.1
%
% xep portion of Onyx Manual.
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\subsection{xep}
\label{xep}
\index{xep@\classname{xep}{}}
The \classname{xep} class implements exception handling, with support for
\cppdef{xep\_try} and \cppmacro{xep\_catch}{} blocks.
Minimal use must include at least:
\begin{verbatim}
xep_begin();
xep_try
{
    /* Code that might throw an exception. */
}
xep_end();
\end{verbatim}

A more complete skeleton looks like:
\begin{verbatim}
xep_begin();
xep_try
{
    /* Code that might throw an exception. */
}
xep_catch(SOME_EXCEPTION)
{
    /* Handle exception... */
    xep_handled();
}
xep_catch(ANOTHER_EXCEPTION)
xep_mcatch(YET_ANOTHER)
{
    /* React to exception, but propagate... */
}
xep_acatch
{
    /* Handle all exceptions not explicitly handled above... */
    xep_handled();
}
xep_end();
\end{verbatim}

Note that there is some serious cpp macro magic behind the \classname{xep}
interface, and as such, if usage deviates significantly from the above
templates, compiler errors may result.

Exception values are of type \ctype{cw\_xepv\_t}.  \cppdef{CW\_ONYXX\_MIN} to
\cppdef{CW\_ONYXX\_MAX} are reserved by \libname{libonyx}, and other ranges may
be reserved by other libraries.  See their documentation for details.

An exception is not implicitly handled if an exception handler is executed for
that exception.  Instead, \cfunc{xep\_handled}{} must be manually called to
avoid propagating the exception up the handler chain.

It is not legal to return from a function within an exception handling code
block, nor is it legal to jump out of an exception handling block; doing so will
corrupt the exception handler chain.

\subsubsection{API}
\begin{capi}
\label{xep_begin}
\index{xep_begin@\cppmacro{xep\_begin}{}}
\citem{\cppmacro[void]{xep\_begin}{void}}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Begin an exception handling code block.
	\end{capilist}
\label{xep_end}
\index{xep_end@\cppmacro{xep\_end}{}}
\citem{\cppmacro[void]{xep\_end}{void}}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		End an exception handling block.
	\end{capilist}
\label{xep_try}
\index{xep_try@\cppdef{xep\_try}}
\citem{\cppdef{xep\_try} \dots}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Begin a block of code that is to be executed, with the
		possibility that an exception might be thrown.
	\end{capilist}
\label{xep_catch}
\index{xep_catch@\cppmacro{xep\_catch}{}}
\citem{\cppmacro{xep\_catch}{cw\_xepv\_t a\_xepv} \dots}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_xepv: ]
			Exception number.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Begin a block of code that catches an exception.  The exception
		is not considered handled unless \cfunc{xep\_handled}{} is
		called.
	\end{capilist}
\label{xep_mcatch}
\index{xep_mcatch@\cppmacro{xep\_mcatch}{}}
\citem{\cppmacro{xep\_mcatch}{cw\_xepv\_t a\_xepv} \dots}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_xepv: ]
			Exception number.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Begin a block of code that catches an exception.  Must
		immediately follow a \cfunc{xep\_catch}{} call.  This interface
		is used for the case where more than one exception type is to be
		handled by the same code block.  The exception is not considered
		handled unless \cfunc{xep\_handled}{} is called.
	\end{capilist}
\label{xep_acatch}
\index{xep_acatch@\cppdef{xep\_acatch}}
\citem{\cppdef{xep\_acatch} \dots}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Begin a block of code that catches all exceptions not explicitly
		caught by \cppmacro{xep\_catch}{} and \cppmacro{xep\_mcatch}{}
		blocks.  There may only be one \cppdef{xep\_acatch} block within
		a try/catch block.  The exception is not considered handled
		unless \cfunc{xep\_handled}{} is called.
	\end{capilist}
\label{xep_value}
\index{xep_value@\cfunc{xep\_value}{}}
\citem{\cfunc[cw\_xepv\_t]{xep\_value}{void}}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Value of the current exception being handled.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return the value of the current exception being handled.
	\end{capilist}
\label{xep_filename}
\index{xep_filename@\cfunc{xep\_filename}{}}
\citem{\cfunc[const char *]{xep\_filename}{void}}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Filename where the current exception being handled was
			thrown.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return the filename where the current exception being handled
		was thrown.
	\end{capilist}
\label{xep_line_num}
\index{xep_line_num@\cfunc{xep\_line\_num}{}}
\citem{\cfunc[uint32\_t]{xep\_line\_num}{void}}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ]
		\begin{description}\item[]
		\item[retval: ]
			Line number where the current exception being handled
			was thrown.
		\end{description}
	\item[Exception(s): ] None.
	\item[Description: ]
		Return the line number where the current exception being handled
		was thrown.
	\end{capilist}
\label{xep_throw_e}
\label{xep_throw}
\index{xep_throw_e@\cfunc{xep\_throw\_e}{}}
\index{xep_throw@\cfunc{xep\_throw}{}}
\citem{\cfunc[void]{xep\_throw\_e}{cw\_xepv\_t a\_xepv, const char *a\_filename,
uint32\_t a\_line\_num}}
\citem{\cfunc[void]{xep\_throw}{cw\_xepv\_t a\_xepv}}
	\begin{capilist}
	\item[Input(s): ]
		\begin{description}\item[]
		\item[a\_xepv: ]
			Exception number to throw.
		\item[a\_filename: ]
			Should be \cppdef{\_\_FILE\_\_}.
		\item[a\_line\_num: ]
			Should be \cppdef{\_\_LINE\_\_}.
		\end{description}
	\item[Output(s): ] None.
	\item[Exception(s): ]
		\begin{description}\item[]
		\item[a\_xepv.]
		\end{description}
	\item[Description: ]
		Throw an exception.
	\end{capilist}
\label{xep_retry}
\index{xep_retry@\cfunc{xep\_retry}{}}
\citem{\cfunc[void]{xep\_retry}{void}}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Implicitly handle the current exception and retry the
		\cppdef{xep\_try} code block.
	\end{capilist}
\label{xep_handled}
\index{xep_handled@\cfunc{xep\_handled}{}}
\citem{\cfunc[void]{xep\_handled}{void}}
	\begin{capilist}
	\item[Input(s): ] None.
	\item[Output(s): ] None.
	\item[Exception(s): ] None.
	\item[Description: ]
		Mark the current exception as handled.
	\end{capilist}
\end{capi}
