doc/poddoc/exception.pod

=head1 Exceptions

Ermyth uses its own exceptions defined in F<util/exception.h>. The example
used in this document will be C<nullpointer_exception>.

=head2 Throwing an exception

To throw an exception, you generally have the following possible syntaxes:

=over

=item throw nullpointer_exception ()

Throw an empty exception.

=item throw nullpointer_exception (char const *fmt, ...)

Throw an exception with a message. This constructor takes varargs like
C<printf> does.

=item throw nullpointer_exception (SRCINF, char const *fmt, ...)

The same as above but include information about the current file, line and
function. exception::what () will look like this:

   file.C(#line): function (): your message

=back

=head2 Adding a new exception

Adding a new exception is as easy as adding a line of C<ADD_EXCEPTION (name, base_class)>.
The F<util/exception.h> file has examples of adding exceptions. C<base_class>
is the exception class from which you want to inherit. That way, you can create
an exception hierarchy within ermyth.

=head2 List of exceptions

=over

=item nullpointer_exception

Thrown whenever a pointer is a C<NULL> pointer where it definately should not be.
C<return_if_fail (ptr != NULL)> should be used in cases where the event is not
exceptional.

=item balloc_exception

Used internally by the block allocator for instance if there is no deallocator
available.

=item module_exception

Currently only thrown if two modules are trying to register themselves with
the same name.

=item factory_exception

Currently unused.

=back
Revision:	1.2
Committed:	Sat Sep 22 14:27:26 2007 UTC (19 years ago) by pippijn
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.1:	+2 -2 lines
Log Message:	split up ermyth into ermyth-modules, libermyth (currently just ermyth-util) and ermyth-core
#	Content
1	=head1 Exceptions
2
3	Ermyth uses its own exceptions defined in F<util/exception.h>. The example
4	used in this document will be C<nullpointer_exception>.
5
6	=head2 Throwing an exception
7
8	To throw an exception, you generally have the following possible syntaxes:
9
10	=over
11
12	=item throw nullpointer_exception ()
13
14	Throw an empty exception.
15
16	=item throw nullpointer_exception (char const *fmt, ...)
17
18	Throw an exception with a message. This constructor takes varargs like
19	C<printf> does.
20
21	=item throw nullpointer_exception (SRCINF, char const *fmt, ...)
22
23	The same as above but include information about the current file, line and
24	function. exception::what () will look like this:
25
26	file.C(#line): function (): your message
27
28	=back
29
30	=head2 Adding a new exception
31
32	Adding a new exception is as easy as adding a line of C<ADD_EXCEPTION (name, base_class)>.
33	The F<util/exception.h> file has examples of adding exceptions. C<base_class>
34	is the exception class from which you want to inherit. That way, you can create
35	an exception hierarchy within ermyth.
36
37	=head2 List of exceptions
38
39	=over
40
41	=item nullpointer_exception
42
43	Thrown whenever a pointer is a C<NULL> pointer where it definately should not be.
44	C<return_if_fail (ptr != NULL)> should be used in cases where the event is not
45	exceptional.
46
47	=item balloc_exception
48
49	Used internally by the block allocator for instance if there is no deallocator
50	available.
51
52	=item module_exception
53
54	Currently only thrown if two modules are trying to register themselves with
55	the same name.
56
57	=item factory_exception
58
59	Currently unused.
60
61	=back