Author: allison Date: Fri Nov 2 07:30:50 2007 New Revision: 22654 Modified: trunk/docs/pdds/pdd23_exceptions.pod
Log: [pdd] Pushing the exceptions PDD to be more in line with the PMC PDD. Modified: trunk/docs/pdds/pdd23_exceptions.pod ============================================================================== --- trunk/docs/pdds/pdd23_exceptions.pod (original) +++ trunk/docs/pdds/pdd23_exceptions.pod Fri Nov 2 07:30:50 2007 @@ -224,60 +224,34 @@ =back -=head1 STANDARD EXCEPTIONS +=head1 IMPLEMENTATION -=head2 Universal Exception Object Interface [Advisory] +=head2 Universal Exception Object Interface All of Parrot's standard exceptions provide at least the following interface. -It is I<STRONGLY RECOMMENDED> that all classes intended for throwing also -provide at least this interface as well. +It is recommended that all classes intended for throwing also provide at least +this interface as well. =over 4 -=item B<PMC *get_message()> +=item B<PMC *get_attr_str(STRING *name)> -Get an exception's human-readable self-description. Note that the type of the -returned PMC isn't required to be C<String>, but you should still be able -to stringify and print it. +Retreive an attribute from the Exception. All exceptions will have at least +C<message>, C<severity>, and C<payload> attributes. -=item B<PMC *get_payload()> +The C<message> is an exception's human-readable self-description. Note that +the type of the returned PMC isn't required to be C<String>, but you should +still be able to stringify and print it. -Get the datum that more specifically identifies the detailed cause/nature of +The C<payload> more specifically identifies the detailed cause/nature of the exception. Each exception class will have its own specific payload type(s). See the table of standard exception classes for examples. -=item B<PMC *get_inner_exception()> -If an exception is a consequence of a previous exception, the -C<get_inner_exception()> method returns that previous exception, else -it returns null. +=item B<PMC *set_attr_str(STRING *name, PMC *value)> -=back - -=head2 Interface of Standard Parrot Exceptions - -Parrot's standard exceptions provide some additional methods beyond the three -universal exception methods shown above. The additional methods are: - -=over 4 - -=item B<init_pmc(PMC *payload)> - -Initialize the exception PMC with the given payload. Note that the payload -will be interpreted differently depending on the specific type of the -exception. For example, the payload of C<exception;errno> is an integer. -In addition, some exceptions don't require payloads, thus: - -=item B<init()> - -Initialize the exception PMC without a payload. Some exceptions are -adequately self-explanatory without payloads. - -=item B<void set_inner_exception(PMC *inner)> - -If an exception is a consequence of a previous exception, use the -C<set_inner_exception()> method to store that previous exception -as part of the exception object. +Set an attribute on the Exception. All exceptions will have at least +C<message>, C<severity>, and C<payload> attributes. =back
