Message/Util/Error.html

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>Message::Util::Error - manakai's Common Error Handling Module</title>
<link rel="stylesheet" href="http://suika.fam.cx/www/style/html/pod.css" type="text/css" />
<link rev="made" href="mailto:admin@suika.fam.cx" />
</head>

<body>

<p><a name="__index__"></a></p>
<!-- INDEX BEGIN -->

<ul>

        <li><a href="#name">NAME</a></li>
        <li><a href="#synopsis">SYNOPSIS</a></li>
        <li><a href="#description">DESCRIPTION</a></li>
        <li><a href="#accessing_error_information">ACCESSING ERROR INFORMATION</a></li>
        <ul>

                <li><a href="#loading_try_and_catch_support">Loading <code>try</code> and <code>catch</code> Support</a></li>
                <li><a href="#methods_on_error_objects">Methods on Error Objects</a></li>
        </ul>

        <li><a href="#throwing_errors">THROWING ERRORS</a></li>
        <ul>

                <li><a href="#error_classes">Error Classes</a></li>
                <li><a href="#error_type_definitions">Error Type Definitions</a></li>
                <li><a href="#throwing_an_error">Throwing an Error</a></li>
                <li><a href="#___report_error_method"><code>___report_error</code> Method</a></li>
                <li><a href="#error_message_construction">Error Message Construction</a></li>
                <li><a href="#formatter_message__util__error__formatter">Formatter Message::Util::Error::formatter</a></li>
        </ul>

        <li><a href="#example">EXAMPLE</a></li>
        <li><a href="#see_also">SEE ALSO</a></li>
        <li><a href="#author">AUTHOR</a></li>
        <li><a href="#license">LICENSE</a></li>
</ul>
<!-- INDEX END -->

<hr />
<p>
</p>
<h1><a name="name">NAME</a></h1>
<p>Message::Util::Error - manakai's Common Error Handling Module</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<p>If you want to catch an exception, whose class
is <em>YourExceptionClass</em>, throwed by a class <em>YourClass</em>:</p>
<pre>
  use YourClass;
  use Message::Util::Error;
  
  my $obj = YourClass-&gt;new;
  
  try {
    $obj-&gt;method_that_throw_an_eception;
  } catch YourExceptionClass with {
    my $err = shift;
    if ($err-&gt;type eq 'NOT_SUPPORTED_ERR') {
      $err-&gt;throw; # die unless catched by upper-level |try| clause (if any)
    } else {
      warn $err;
    }
  };</pre>
<p>If you want to build a class <em>YourClass</em> that
throws an exception based on <code>Message::Util::Error</code>:</p>
<pre>
  package YourClass;
  
  sub method_that_throw_an_exception ($) {
    my $self = shift;
    report YourExceptionClass
        -object =&gt; $self,
        -type =&gt; 'EXAMPLE_ERR',
        -subtype =&gt; 'EXAMPLE_SPECIFIC_ERR';
  } # method_that_throw_an_exception
  
  ## |report| calls back this method.  If this method |throw|s
  ## the exception, then it is really thrown.
  sub ___report_error ($$) {
    my ($self, $err) = @_;
    if ($err-&gt;type_def-&gt;{level} eq 'warning') {
      warn $err;
    } else {
      $err-&gt;throw;
    }
  } # ___report_error
  
  package YourExceptionClass;
  use Message::Util::Error;
  push our @ISA, 'Message::Util::Error';
  
  sub ___error_def () {
    return {
      EXAMPLE_ERR =&gt; {
        -description =&gt; q&lt;An example error condition&gt;,
        -subtype =&gt; {
          EXAMPLE_SPECIFIC_ERR =&gt; {
            -description =&gt; q&lt;A specific example error condition&gt;,
          },
        },
        level =&gt; 'fatal',
      },
    };
  } # ___error_def</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p>Various manakai classes throws exceptions, in particular
<code>DOMException</code>s in DOM implementation classes.  In addition,
it might report other kinds of errors, such as <code>DOMError</code>
as defined in DOM Level 3 Core specification.  This module,
<code>Message::Util::Error</code>, provides an integrated framework
for reporting exceptions, errors, warnings, and so on.</p>
<p>The <code>Message::Util::Error</code> exception framework is built on
the top of the Perl module <code>Error</code>, which apply to Perl scripts
the <code>try</code> and <code>catch</code> functionalities.  Exceptions
thrown using <code>Message::Util::Error</code> exception framework
are also able to be catched by the <code>catch</code> clause as in
the original <code>Error</code> module.  For more information on
usage for <code>try</code>, <code>catch</code>, and other clauses, see
the documentatin for the <code>Error</code> module.  This document
describes some <code>Message::Util::Error</code>-specific conventions,
mainly targeted for manakai module authors.</p>
<p>For other usages of the framework, such as <code>DOMError</code>,
see documentation for each module.</p>
<p>This module is part of manakai.</p>
<p>
</p>
<hr />
<h1><a name="accessing_error_information">ACCESSING ERROR INFORMATION</a></h1>
<p>
</p>
<h2><a name="loading_try_and_catch_support">Loading <code>try</code> and <code>catch</code> Support</a></h2>
<p>If you'd like to use <code>try</code> and <code>catch</code> clauses, you
have to import these names by:</p>
<pre>
  use Message::Util::Error;</pre>
<p>Note that the example above is equivalent to:</p>
<pre>
  use Error qw(:try);</pre>
<p>except that in the former example <code>Message::Util::Error</code>
module is also loaded if not yet.</p>
<p>
</p>
<h2><a name="methods_on_error_objects">Methods on Error Objects</a></h2>
<p><em>Any method defined on an <code>Error</code> object is also available</em>
for <code>Message::Util::Error</code> objects with the same semantics
(though some might be overridden).  In addition,
a few methods are added for <code>Message::Util::Error</code> objects.</p>
<dl>
<dt><strong><a name="item_code"><em>$code</em> = <em>$err</em>-&gt;code;</a></strong><br />
</dt>
<dd>
Returns the code of the error.
</dd>
<dd>
<p>If the definition for the error type has a code associated,
then it is returned.  Otherwise, <code>0</code> is returned.</p>
</dd>
<dd>
<p>This method is added for DOM compatibility.</p>
</dd>
<p></p>
<dt><strong><a name="item_subtype"><em>$subtype</em> = <em>$err</em>-&gt;subtype;</a></strong><br />
</dt>
<dd>
Returns the subtype of the error, if specified when the
error object is created, or <code>undef</code> otherwise.
</dd>
<p></p>
<dt><strong><a name="item_text"><em>$text</em> = <em>$err</em>-&gt;text;</a></strong><br />
</dt>
<dd>
Returns the text of the error.
</dd>
<dd>
<p><em>This method is defined in <code>Error</code> module but overridden.</em>
If the definition for the error subtype, if any, has a description,
then it is returned.  Otherwise, if the definition for the error type
has a description, then it is returned.  Otherwise, 
same as <code>Error</code>'s definition, i.e. the text specified
when the <code>Error</code> object is created, if any, or <code>undef</code> otherwise,
is returned.</p>
</dd>
<p></p>
<dt><strong><a name="item_type"><em>$text</em> = <em>$err</em>-&gt;type;</a></strong><br />
</dt>
<dd>
Returns the type of the error specified when the error is created.
</dd>
<p></p>
<dt><strong><a name="item_type_def"><em>$def</em> = <em>$err</em>-&gt;type_def;</a></strong><br />
</dt>
<dd>
Returns the definition for the error type, if any, 
or the definition for the <code>UNKNOWN</code> type, otherwise.
For the content of the error type definition,
see <a href="#error_type_definitions">Error Type Definitions</a>.  Applications
MUST NOT modify the error type definition.  If modified
then the result is undefined and it might make the error handling
behaviour inconsistent or incorrect.
</dd>
<p></p>
<dt><strong><a name="item_value"><em>$value</em> = <em>$err</em>-&gt;value; <em>$value</em> = 0+<em>$err</em>;</a></strong><br />
</dt>
<dd>
Returns the value that can be associated with the error.
</dd>
<dd>
<p><em>This method is defined in <code>Error</code> module but overridden.</em>
If the definition for the error type has a code associated,
then it is returned.  Otherwise, 
same as <code>Error</code>'s definition, i.e. the value specified
when the <code>Error</code> object is created, if any, or <code>undef</code> otherwise,
is returned.</p>
</dd>
<p></p></dl>
<p>
</p>
<hr />
<h1><a name="throwing_errors">THROWING ERRORS</a></h1>
<p>@@</p>
<p>1. Define an error class.</p>
<p>2. Define the <code>___report_error</code> method to the class
whose methods will report errors.  (REQUIRED
if you use <code>report</code>.)</p>
<p>3. Define an error message template class.  (REQUIRED
if you want to extend the error message parameter set.)</p>
<p>4. Put <code>report</code> or <code>throw</code> where you want to report
or throw an error.</p>
<p>5. Ensure the error class is loaded when any statement
added by Step 4 is executed.</p>
<p>
</p>
<h2><a name="error_classes">Error Classes</a></h2>
<p>@@</p>
<p>
</p>
<h2><a name="error_type_definitions">Error Type Definitions</a></h2>
<p>@@</p>
<p>Error type:</p>
<dl>
<dt><strong><a name="item__2dcode">-code</a></strong><br />
</dt>
<dd>
Numeric error code for the type.  If specified,
it MUST be a number.
</dd>
<p></p>
<dt><strong><a name="item__2ddescription">-description</a></strong><br />
</dt>
<dd>
A template that is used to create the description
for an error with that type.
@@ See @@ for template syntax.
</dd>
<p></p>
<dt><strong><a name="item__2dsubtype">-subtype</a></strong><br />
</dt>
<dd>
A reference to hash that contains pairs of 
error subtype nams and error subtype definitions.
It MAY contain zero or more error subtypes.
</dd>
<p></p></dl>
<p>Error subtype:</p>
<dl>
<dt><strong>-description</strong><br />
</dt>
<dd>
A template that is used to create the description
for an error with that subtype.
@@ See @@ for template syntax.
</dd>
<p></p></dl>
<p>Any other value starts with <code>-</code> is reserved for future extension
and MUST NOT be used for any purpose until it is eventually defined.
Values <em>not</em> start with <code>-</code> MAY be used for subclass-specific
error type/subtype properties.</p>
<p>
</p>
<h2><a name="throwing_an_error">Throwing an Error</a></h2>
<p>@@</p>
<dl>
<dt><strong><a name="item_def">-def (MUST NOT be specified)</a></strong><br />
</dt>
<dd>
The definition for the error type.
</dd>
<dd>
<p>This parameter MUST NOT be specified when a 
<code>Message::Util::Error</code> object is created.
It will be supplied by the constructor of the error object.
If any value is specified, it will be ignored.</p>
</dd>
<dd>
<p>If no definition for the error type is found,
then the definition for the <code>UNKNOWN</code> type is used;
if there is no such definition, then the error constructor
<code>die</code>s.</p>
</dd>
<p></p>
<dt><strong><a name="item_file">-file (MUST NOT be specified)</a></strong><br />
</dt>
<dd>
The file name where an error is reported.
</dd>
<dd>
<p>This parameter MUST NOT be specified when a
<code>Message::Util::Error</code> object is created.
It will be supplied by the constructor of the error object.
If any value is specified, it will be ignored.</p>
</dd>
<p></p>
<dt><strong><a name="item_line">-line (MUST NOT be specified)</a></strong><br />
</dt>
<dd>
The line number where an error is reported.
</dd>
<dd>
<p>This parameter MUST NOT be specified when a
<code>Message::Util::Error</code> object is created.
It will be supplied by the constructor of the error object.
If any value is specified, it will be ignored.</p>
</dd>
<p></p>
<dt><strong><a name="item__2dobject">-object</a></strong><br />
</dt>
<dd>
The object for which an error is reported.
</dd>
<dd>
<p>If specified, the value MUST be an object
that has a <code>___report_error</code> method.
Otherwise, Perl will report some error.</p>
</dd>
<p></p>
<dt><strong><a name="item_package">-package (MUST NOT be specified)</a></strong><br />
</dt>
<dd>
The package name where an error is reported.
</dd>
<dd>
<p>This parameter MUST NOT be specified when a
<code>Message::Util::Error</code> object is created.
It will be supplied by the constructor of the error object.
If any value is specified, it will be ignored.</p>
</dd>
<p></p>
<dt><strong><a name="item_stacktrace">-stacktrace (MUST NOT be specified)</a></strong><br />
</dt>
<dd>
The trace of the function call stack (used by <code>Error</code> module).
</dd>
<dd>
<p>This parameter MUST NOT be specified when a
<code>Message::Util::Error</code> object is created.
It will be supplied by the constructor of the error object.
If any value is specified, it will be ignored.</p>
</dd>
<p></p>
<dt><strong><a name="item_stacktrace_">-stacktrace_ (MUST NOT be specified)</a></strong><br />
</dt>
<dd>
The trace of the function call stack (used by <code>Message::Util::Error</code>
module).
</dd>
<dd>
<p>This parameter MUST NOT be specified when a
<code>Message::Util::Error</code> object is created.
It will be supplied by the constructor of the error object.
If any value is specified, it will be ignored.</p>
</dd>
<p></p>
<dt><strong>-subtype</strong><br />
</dt>
<dd>
The subtype of the error.  It may or may not be specified.
</dd>
<p></p>
<dt><strong><a name="item__2dtext">-text</a></strong><br />
</dt>
<dd>
The text of the error.  Note that this option is less
useful in <code>Message::Util::Error</code> where <a href="#item__2ddescription"><code>-description</code></a>
in error type/subtype definitions take precedence in the <a href="#item_text"><code>text</code></a> method.
</dd>
<p></p>
<dt><strong>-type (REQUIRED)</strong><br />
</dt>
<dd>
The error type.
</dd>
<dd>
<p>This parameter MUST be specified when
a <code>Message::Util::Error</code> object is created.
If this option is missing when creating an error object,
then the error constructor <code>die</code>s.</p>
</dd>
<p></p>
<dt><strong><a name="item__2dvalue">-value</a></strong><br />
</dt>
<dd>
The value of the error.  Note that this option is less
useful in <code>Message::Util::Error</code> where <a href="#item__2dcode"><code>-code</code></a>
in error type definition take precedence in the <a href="#item_value"><code>value</code></a> method.
</dd>
<p></p></dl>
<p>Any other value starts with <code>-</code> is reserved for future extension
and MUST NOT be used for any purpose until it is eventually defined.
Values <em>not</em> start with <code>-</code> MAY be used for subclass-specific
error properties.</p>
<p>
</p>
<h2><a name="___report_error_method"><code>___report_error</code> Method</a></h2>
<p>@@</p>
<p>
</p>
<h2><a name="error_message_construction">Error Message Construction</a></h2>
<p>@@ NEED TO BE REWRITTEN</p>
<p>Human readable error message text, returned by <a href="#item_text"><code>text</code></a> method,
is generated from <code>description</code> parameter of error definition.</p>
<p>Format defined by <a href="../../../Message/Util/Formatter.html">the Message::Util::Formatter manpage</a> is used to specify
<code>description</code> parameter and it is processed by the formatter.</p>
<dl>
<dt><strong><a name="item_sub_error_subclass_3a_3a_formatter_package___7b_re">sub ERROR_SUBCLASS::_FORMATTER_PACKAGE_ { return $class_name }</a></strong><br />
</dt>
<dd>
Subclass can define <code>_FORMATTER_PACKAGE_</code> method
to define class name of the formatter.  Defaulted to
<code>Message::Util::Error::formatter</code>.
</dd>
<dd>
<p>Unless you wish to use additional rules in template text 
(<code>description</code> parameter), you don't need to define this
method in your subclass.</p>
</dd>
<dd>
<p>Class returned by this method MUST be a subclass (descender class) of
<code>Message::Util::Formatter::Base</code>.</p>
</dd>
<p></p></dl>
<p>
</p>
<h2><a name="formatter_message__util__error__formatter">Formatter Message::Util::Error::formatter</a></h2>
<p>In addition to rules defined in <code>Message::Util::Formatter::Text</code>,
formatter <code>Message::Util::Error::formatter</code> defines some rules:</p>
<dl>
<dt><strong><a name="item__name_">%name;</a></strong><br />
</dt>
<dd>
Error type name (<code>-type</code> parameter specified when error is thrown)
</dd>
<p></p>
<dt><strong><a name="item_t">%t (name =&gt; parameter-name);</a></strong><br />
</dt>
<dd>
Parameter value specified when error is thrown
</dd>
<p></p></dl>
<p>
</p>
<hr />
<h1><a name="example">EXAMPLE</a></h1>
<p>@@ MAYBE WE CAN REMOVE THIS SECTION</p>
<p>To make a new error class:</p>
<pre>
  package SomeExceptionClass;
  use Message::Util::Error;
  push our @ISA, 'Message::Util::Error';
  
  ## [REQUIRED] Error types
  sub ___error_def {
    ## Returns a reference to hash defining error type
    return {
      ERROR_NAME =&gt; {
        description =&gt; q(%name;: %t (name =&gt; what); is bad),
        level =&gt; 'fatal',
        ...
      },
      WARNING_NAME =&gt; {
        description =&gt; q(%name;: %t (name =&gt; what); might be bad),
        level =&gt; 'warn',
        ...
      },
      ...
    };
  }
  
  ## [OPTIONAL] Package name of formatter constructing error message
  ##            (Default: Message::Util::Error::formatter)
  sub _FORMATTER_PACKAGE_ () { 'SomeFormatterClass' }</pre>
<p>Throwing exception:</p>
<pre>
  use SomeExceptionClass;
  ...
  do something;
  ...
  throw SomeExceptionClass -type =&gt; 'ERROR_NAME',
                           what =&gt; 'Example';</pre>
<p>If you implements an object-oriented class:</p>
<pre>
  package SomeModule;
  use SomeExceptionClass;
  
  sub some_method {
    my $self = shift;
    ...
    report SomeExceptionClass
      -type =&gt; 'ERROR_NAME',
      what =&gt; 'Non-oo programing',
      -object =&gt; $self, method =&gt; 'some_method'
        unless $oo;
    ...
    report SomeExceptionClass
      -type =&gt; 'WARNING_NAME',
      what =&gt; 'This module',
      -object =&gt; $self, method =&gt; 'some_method';
    ...
  }
  
  ## If you use &quot;report&quot;, you must implements this internal method
  sub ___report_error ($$;%) {
    my ($self, $err, %option) = @_;
    ## Throwing if fatal
    if ($err-&gt;{def}-&gt;{level} eq 'fatal') {
      $err-&gt;throw;
      print &quot;This text never printed&quot;;
    ## Otherwise warning only
    } else {
      warn $err-&gt;stringify;
      print &quot;This text IS printed&quot;;
    }
  }</pre>
<p>
</p>
<hr />
<h1><a name="see_also">SEE ALSO</a></h1>
<p><em>Error</em></p>
<p><a href="../../../Message/DOM/DOMException.html">the Message::DOM::DOMException manpage</a></p>
<p><a href="../../../Message/DOM/DOMError.html">the Message::DOM::DOMError manpage</a></p>
<p>
</p>
<hr />
<h1><a name="author">AUTHOR</a></h1>
<p>Wakaba &lt;<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>&gt;</p>
<p>
</p>
<hr />
<h1><a name="license">LICENSE</a></h1>
<p>Copyright 2003-2007 Wakaba &lt;<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>&gt;</p>
<p>This program is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.</p>

</body>

</html>
1	wakaba	1.1	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
2			<html xmlns="http://www.w3.org/1999/xhtml">
3			<head>
4			<title>Message::Util::Error - manakai's Common Error Handling Module</title>
5			<link rel="stylesheet" href="http://suika.fam.cx/www/style/html/pod.css" type="text/css" />
6			<link rev="made" href="mailto:admin@suika.fam.cx" />
7			</head>
8
9			<body>
10
11			<p><a name="__index__"></a></p>
12			<!-- INDEX BEGIN -->
13
14			<ul>
15
16			<li><a href="#name">NAME</a></li>
17			<li><a href="#synopsis">SYNOPSIS</a></li>
18			<li><a href="#description">DESCRIPTION</a></li>
19			<li><a href="#accessing_error_information">ACCESSING ERROR INFORMATION</a></li>
20			<ul>
21
22			<li><a href="#loading_try_and_catch_support">Loading <code>try</code> and <code>catch</code> Support</a></li>
23			<li><a href="#methods_on_error_objects">Methods on Error Objects</a></li>
24			</ul>
25
26			<li><a href="#throwing_errors">THROWING ERRORS</a></li>
27			<ul>
28
29			<li><a href="#error_classes">Error Classes</a></li>
30			<li><a href="#error_type_definitions">Error Type Definitions</a></li>
31			<li><a href="#throwing_an_error">Throwing an Error</a></li>
32			<li><a href="#___report_error_method"><code>___report_error</code> Method</a></li>
33			<li><a href="#error_message_construction">Error Message Construction</a></li>
34			<li><a href="#formatter_message__util__error__formatter">Formatter Message::Util::Error::formatter</a></li>
35			</ul>
36
37			<li><a href="#example">EXAMPLE</a></li>
38			<li><a href="#see_also">SEE ALSO</a></li>
39			<li><a href="#author">AUTHOR</a></li>
40			<li><a href="#license">LICENSE</a></li>
41			</ul>
42			<!-- INDEX END -->
43
44			<hr />
45			<p>
46			</p>
47			<h1><a name="name">NAME</a></h1>
48			<p>Message::Util::Error - manakai's Common Error Handling Module</p>
49			<p>
50			</p>
51			<hr />
52			<h1><a name="synopsis">SYNOPSIS</a></h1>
53			<p>If you want to catch an exception, whose class
54			is <em>YourExceptionClass</em>, throwed by a class <em>YourClass</em>:</p>
55			<pre>
56			use YourClass;
57			use Message::Util::Error;
58
59			my $obj = YourClass->new;
60
61			try {
62			$obj->method_that_throw_an_eception;
63			} catch YourExceptionClass with {
64			my $err = shift;
65			if ($err->type eq 'NOT_SUPPORTED_ERR') {
66			$err->throw; # die unless catched by upper-level \|try\| clause (if any)
67			} else {
68			warn $err;
69			}
70			};</pre>
71			<p>If you want to build a class <em>YourClass</em> that
72			throws an exception based on <code>Message::Util::Error</code>:</p>
73			<pre>
74			package YourClass;
75
76			sub method_that_throw_an_exception ($) {
77			my $self = shift;
78			report YourExceptionClass
79			-object => $self,
80			-type => 'EXAMPLE_ERR',
81			-subtype => 'EXAMPLE_SPECIFIC_ERR';
82			} # method_that_throw_an_exception
83
84			## \|report\| calls back this method. If this method \|throw\|s
85			## the exception, then it is really thrown.
86			sub ___report_error ($$) {
87			my ($self, $err) = @_;
88			if ($err->type_def->{level} eq 'warning') {
89			warn $err;
90			} else {
91			$err->throw;
92			}
93			} # ___report_error
94
95			package YourExceptionClass;
96			use Message::Util::Error;
97			push our @ISA, 'Message::Util::Error';
98
99			sub ___error_def () {
100			return {
101			EXAMPLE_ERR => {
102			-description => q<An example error condition>,
103			-subtype => {
104			EXAMPLE_SPECIFIC_ERR => {
105			-description => q<A specific example error condition>,
106			},
107			},
108			level => 'fatal',
109			},
110			};
111			} # ___error_def</pre>
112			<p>
113			</p>
114			<hr />
115			<h1><a name="description">DESCRIPTION</a></h1>
116			<p>Various manakai classes throws exceptions, in particular
117			<code>DOMException</code>s in DOM implementation classes. In addition,
118			it might report other kinds of errors, such as <code>DOMError</code>
119			as defined in DOM Level 3 Core specification. This module,
120			<code>Message::Util::Error</code>, provides an integrated framework
121			for reporting exceptions, errors, warnings, and so on.</p>
122			<p>The <code>Message::Util::Error</code> exception framework is built on
123			the top of the Perl module <code>Error</code>, which apply to Perl scripts
124			the <code>try</code> and <code>catch</code> functionalities. Exceptions
125			thrown using <code>Message::Util::Error</code> exception framework
126			are also able to be catched by the <code>catch</code> clause as in
127			the original <code>Error</code> module. For more information on
128			usage for <code>try</code>, <code>catch</code>, and other clauses, see
129			the documentatin for the <code>Error</code> module. This document
130			describes some <code>Message::Util::Error</code>-specific conventions,
131			mainly targeted for manakai module authors.</p>
132			<p>For other usages of the framework, such as <code>DOMError</code>,
133			see documentation for each module.</p>
134			<p>This module is part of manakai.</p>
135			<p>
136			</p>
137			<hr />
138			<h1><a name="accessing_error_information">ACCESSING ERROR INFORMATION</a></h1>
139			<p>
140			</p>
141			<h2><a name="loading_try_and_catch_support">Loading <code>try</code> and <code>catch</code> Support</a></h2>
142			<p>If you'd like to use <code>try</code> and <code>catch</code> clauses, you
143			have to import these names by:</p>
144			<pre>
145			use Message::Util::Error;</pre>
146			<p>Note that the example above is equivalent to:</p>
147			<pre>
148			use Error qw(:try);</pre>
149			<p>except that in the former example <code>Message::Util::Error</code>
150			module is also loaded if not yet.</p>
151			<p>
152			</p>
153			<h2><a name="methods_on_error_objects">Methods on Error Objects</a></h2>
154			<p><em>Any method defined on an <code>Error</code> object is also available</em>
155			for <code>Message::Util::Error</code> objects with the same semantics
156			(though some might be overridden). In addition,
157			a few methods are added for <code>Message::Util::Error</code> objects.</p>
158			<dl>
159			<dt><strong><a name="item_code"><em>$code</em> = <em>$err</em>->code;</a></strong><br />
160			</dt>
161			<dd>
162			Returns the code of the error.
163			</dd>
164			<dd>
165			<p>If the definition for the error type has a code associated,
166			then it is returned. Otherwise, <code>0</code> is returned.</p>
167			</dd>
168			<dd>
169			<p>This method is added for DOM compatibility.</p>
170			</dd>
171			<p></p>
172			<dt><strong><a name="item_subtype"><em>$subtype</em> = <em>$err</em>->subtype;</a></strong><br />
173			</dt>
174			<dd>
175			Returns the subtype of the error, if specified when the
176			error object is created, or <code>undef</code> otherwise.
177			</dd>
178			<p></p>
179			<dt><strong><a name="item_text"><em>$text</em> = <em>$err</em>->text;</a></strong><br />
180			</dt>
181			<dd>
182			Returns the text of the error.
183			</dd>
184			<dd>
185			<p><em>This method is defined in <code>Error</code> module but overridden.</em>
186			If the definition for the error subtype, if any, has a description,
187			then it is returned. Otherwise, if the definition for the error type
188			has a description, then it is returned. Otherwise,
189			same as <code>Error</code>'s definition, i.e. the text specified
190			when the <code>Error</code> object is created, if any, or <code>undef</code> otherwise,
191			is returned.</p>
192			</dd>
193			<p></p>
194			<dt><strong><a name="item_type"><em>$text</em> = <em>$err</em>->type;</a></strong><br />
195			</dt>
196			<dd>
197			Returns the type of the error specified when the error is created.
198			</dd>
199			<p></p>
200			<dt><strong><a name="item_type_def"><em>$def</em> = <em>$err</em>->type_def;</a></strong><br />
201			</dt>
202			<dd>
203			Returns the definition for the error type, if any,
204			or the definition for the <code>UNKNOWN</code> type, otherwise.
205			For the content of the error type definition,
206			see <a href="#error_type_definitions">Error Type Definitions</a>. Applications
207			MUST NOT modify the error type definition. If modified
208			then the result is undefined and it might make the error handling
209			behaviour inconsistent or incorrect.
210			</dd>
211			<p></p>
212			<dt><strong><a name="item_value"><em>$value</em> = <em>$err</em>->value; <em>$value</em> = 0+<em>$err</em>;</a></strong><br />
213			</dt>
214			<dd>
215			Returns the value that can be associated with the error.
216			</dd>
217			<dd>
218			<p><em>This method is defined in <code>Error</code> module but overridden.</em>
219			If the definition for the error type has a code associated,
220			then it is returned. Otherwise,
221			same as <code>Error</code>'s definition, i.e. the value specified
222			when the <code>Error</code> object is created, if any, or <code>undef</code> otherwise,
223			is returned.</p>
224			</dd>
225			<p></p></dl>
226			<p>
227			</p>
228			<hr />
229			<h1><a name="throwing_errors">THROWING ERRORS</a></h1>
230			<p>@@</p>
231			<p>1. Define an error class.</p>
232			<p>2. Define the <code>___report_error</code> method to the class
233			whose methods will report errors. (REQUIRED
234			if you use <code>report</code>.)</p>
235			<p>3. Define an error message template class. (REQUIRED
236			if you want to extend the error message parameter set.)</p>
237			<p>4. Put <code>report</code> or <code>throw</code> where you want to report
238			or throw an error.</p>
239			<p>5. Ensure the error class is loaded when any statement
240			added by Step 4 is executed.</p>
241			<p>
242			</p>
243			<h2><a name="error_classes">Error Classes</a></h2>
244			<p>@@</p>
245			<p>
246			</p>
247			<h2><a name="error_type_definitions">Error Type Definitions</a></h2>
248			<p>@@</p>
249			<p>Error type:</p>
250			<dl>
251			<dt><strong><a name="item__2dcode">-code</a></strong><br />
252			</dt>
253			<dd>
254			Numeric error code for the type. If specified,
255			it MUST be a number.
256			</dd>
257			<p></p>
258			<dt><strong><a name="item__2ddescription">-description</a></strong><br />
259			</dt>
260			<dd>
261			A template that is used to create the description
262			for an error with that type.
263			@@ See @@ for template syntax.
264			</dd>
265			<p></p>
266			<dt><strong><a name="item__2dsubtype">-subtype</a></strong><br />
267			</dt>
268			<dd>
269			A reference to hash that contains pairs of
270			error subtype nams and error subtype definitions.
271			It MAY contain zero or more error subtypes.
272			</dd>
273			<p></p></dl>
274			<p>Error subtype:</p>
275			<dl>
276			<dt><strong>-description</strong><br />
277			</dt>
278			<dd>
279			A template that is used to create the description
280			for an error with that subtype.
281			@@ See @@ for template syntax.
282			</dd>
283			<p></p></dl>
284			<p>Any other value starts with <code>-</code> is reserved for future extension
285			and MUST NOT be used for any purpose until it is eventually defined.
286			Values <em>not</em> start with <code>-</code> MAY be used for subclass-specific
287			error type/subtype properties.</p>
288			<p>
289			</p>
290			<h2><a name="throwing_an_error">Throwing an Error</a></h2>
291			<p>@@</p>
292			<dl>
293			<dt><strong><a name="item_def">-def (MUST NOT be specified)</a></strong><br />
294			</dt>
295			<dd>
296			The definition for the error type.
297			</dd>
298			<dd>
299			<p>This parameter MUST NOT be specified when a
300			<code>Message::Util::Error</code> object is created.
301			It will be supplied by the constructor of the error object.
302			If any value is specified, it will be ignored.</p>
303			</dd>
304			<dd>
305			<p>If no definition for the error type is found,
306			then the definition for the <code>UNKNOWN</code> type is used;
307			if there is no such definition, then the error constructor
308			<code>die</code>s.</p>
309			</dd>
310			<p></p>
311			<dt><strong><a name="item_file">-file (MUST NOT be specified)</a></strong><br />
312			</dt>
313			<dd>
314			The file name where an error is reported.
315			</dd>
316			<dd>
317			<p>This parameter MUST NOT be specified when a
318			<code>Message::Util::Error</code> object is created.
319			It will be supplied by the constructor of the error object.
320			If any value is specified, it will be ignored.</p>
321			</dd>
322			<p></p>
323			<dt><strong><a name="item_line">-line (MUST NOT be specified)</a></strong><br />
324			</dt>
325			<dd>
326			The line number where an error is reported.
327			</dd>
328			<dd>
329			<p>This parameter MUST NOT be specified when a
330			<code>Message::Util::Error</code> object is created.
331			It will be supplied by the constructor of the error object.
332			If any value is specified, it will be ignored.</p>
333			</dd>
334			<p></p>
335			<dt><strong><a name="item__2dobject">-object</a></strong><br />
336			</dt>
337			<dd>
338			The object for which an error is reported.
339			</dd>
340			<dd>
341			<p>If specified, the value MUST be an object
342			that has a <code>___report_error</code> method.
343			Otherwise, Perl will report some error.</p>
344			</dd>
345			<p></p>
346			<dt><strong><a name="item_package">-package (MUST NOT be specified)</a></strong><br />
347			</dt>
348			<dd>
349			The package name where an error is reported.
350			</dd>
351			<dd>
352			<p>This parameter MUST NOT be specified when a
353			<code>Message::Util::Error</code> object is created.
354			It will be supplied by the constructor of the error object.
355			If any value is specified, it will be ignored.</p>
356			</dd>
357			<p></p>
358			<dt><strong><a name="item_stacktrace">-stacktrace (MUST NOT be specified)</a></strong><br />
359			</dt>
360			<dd>
361			The trace of the function call stack (used by <code>Error</code> module).
362			</dd>
363			<dd>
364			<p>This parameter MUST NOT be specified when a
365			<code>Message::Util::Error</code> object is created.
366			It will be supplied by the constructor of the error object.
367			If any value is specified, it will be ignored.</p>
368			</dd>
369			<p></p>
370			<dt><strong><a name="item_stacktrace_">-stacktrace_ (MUST NOT be specified)</a></strong><br />
371			</dt>
372			<dd>
373			The trace of the function call stack (used by <code>Message::Util::Error</code>
374			module).
375			</dd>
376			<dd>
377			<p>This parameter MUST NOT be specified when a
378			<code>Message::Util::Error</code> object is created.
379			It will be supplied by the constructor of the error object.
380			If any value is specified, it will be ignored.</p>
381			</dd>
382			<p></p>
383			<dt><strong>-subtype</strong><br />
384			</dt>
385			<dd>
386			The subtype of the error. It may or may not be specified.
387			</dd>
388			<p></p>
389			<dt><strong><a name="item__2dtext">-text</a></strong><br />
390			</dt>
391			<dd>
392			The text of the error. Note that this option is less
393			useful in <code>Message::Util::Error</code> where <a href="#item__2ddescription"><code>-description</code></a>
394			in error type/subtype definitions take precedence in the <a href="#item_text"><code>text</code></a> method.
395			</dd>
396			<p></p>
397			<dt><strong>-type (REQUIRED)</strong><br />
398			</dt>
399			<dd>
400			The error type.
401			</dd>
402			<dd>
403			<p>This parameter MUST be specified when
404			a <code>Message::Util::Error</code> object is created.
405			If this option is missing when creating an error object,
406			then the error constructor <code>die</code>s.</p>
407			</dd>
408			<p></p>
409			<dt><strong><a name="item__2dvalue">-value</a></strong><br />
410			</dt>
411			<dd>
412			The value of the error. Note that this option is less
413			useful in <code>Message::Util::Error</code> where <a href="#item__2dcode"><code>-code</code></a>
414			in error type definition take precedence in the <a href="#item_value"><code>value</code></a> method.
415			</dd>
416			<p></p></dl>
417			<p>Any other value starts with <code>-</code> is reserved for future extension
418			and MUST NOT be used for any purpose until it is eventually defined.
419			Values <em>not</em> start with <code>-</code> MAY be used for subclass-specific
420			error properties.</p>
421			<p>
422			</p>
423			<h2><a name="___report_error_method"><code>___report_error</code> Method</a></h2>
424			<p>@@</p>
425			<p>
426			</p>
427			<h2><a name="error_message_construction">Error Message Construction</a></h2>
428			<p>@@ NEED TO BE REWRITTEN</p>
429			<p>Human readable error message text, returned by <a href="#item_text"><code>text</code></a> method,
430			is generated from <code>description</code> parameter of error definition.</p>
431			<p>Format defined by <a href="../../../Message/Util/Formatter.html">the Message::Util::Formatter manpage</a> is used to specify
432			<code>description</code> parameter and it is processed by the formatter.</p>
433			<dl>
434			<dt><strong><a name="item_sub_error_subclass_3a_3a_formatter_package___7b_re">sub ERROR_SUBCLASS::_FORMATTER_PACKAGE_ { return $class_name }</a></strong><br />
435			</dt>
436			<dd>
437			Subclass can define <code>_FORMATTER_PACKAGE_</code> method
438			to define class name of the formatter. Defaulted to
439			<code>Message::Util::Error::formatter</code>.
440			</dd>
441			<dd>
442			<p>Unless you wish to use additional rules in template text
443			(<code>description</code> parameter), you don't need to define this
444			method in your subclass.</p>
445			</dd>
446			<dd>
447			<p>Class returned by this method MUST be a subclass (descender class) of
448			<code>Message::Util::Formatter::Base</code>.</p>
449			</dd>
450			<p></p></dl>
451			<p>
452			</p>
453			<h2><a name="formatter_message__util__error__formatter">Formatter Message::Util::Error::formatter</a></h2>
454			<p>In addition to rules defined in <code>Message::Util::Formatter::Text</code>,
455			formatter <code>Message::Util::Error::formatter</code> defines some rules:</p>
456			<dl>
457			<dt><strong><a name="item__name_">%name;</a></strong><br />
458			</dt>
459			<dd>
460			Error type name (<code>-type</code> parameter specified when error is thrown)
461			</dd>
462			<p></p>
463			<dt><strong><a name="item_t">%t (name => parameter-name);</a></strong><br />
464			</dt>
465			<dd>
466			Parameter value specified when error is thrown
467			</dd>
468			<p></p></dl>
469			<p>
470			</p>
471			<hr />
472			<h1><a name="example">EXAMPLE</a></h1>
473			<p>@@ MAYBE WE CAN REMOVE THIS SECTION</p>
474			<p>To make a new error class:</p>
475			<pre>
476			package SomeExceptionClass;
477			use Message::Util::Error;
478			push our @ISA, 'Message::Util::Error';
479
480			## [REQUIRED] Error types
481			sub ___error_def {
482			## Returns a reference to hash defining error type
483			return {
484			ERROR_NAME => {
485			description => q(%name;: %t (name => what); is bad),
486			level => 'fatal',
487			...
488			},
489			WARNING_NAME => {
490			description => q(%name;: %t (name => what); might be bad),
491			level => 'warn',
492			...
493			},
494			...
495			};
496			}
497
498			## [OPTIONAL] Package name of formatter constructing error message
499			## (Default: Message::Util::Error::formatter)
500			sub _FORMATTER_PACKAGE_ () { 'SomeFormatterClass' }</pre>
501			<p>Throwing exception:</p>
502			<pre>
503			use SomeExceptionClass;
504			...
505			do something;
506			...
507			throw SomeExceptionClass -type => 'ERROR_NAME',
508			what => 'Example';</pre>
509			<p>If you implements an object-oriented class:</p>
510			<pre>
511			package SomeModule;
512			use SomeExceptionClass;
513
514			sub some_method {
515			my $self = shift;
516			...
517			report SomeExceptionClass
518			-type => 'ERROR_NAME',
519			what => 'Non-oo programing',
520			-object => $self, method => 'some_method'
521			unless $oo;
522			...
523			report SomeExceptionClass
524			-type => 'WARNING_NAME',
525			what => 'This module',
526			-object => $self, method => 'some_method';
527			...
528			}
529
530			## If you use "report", you must implements this internal method
531			sub ___report_error ($$;%) {
532			my ($self, $err, %option) = @_;
533			## Throwing if fatal
534			if ($err->{def}->{level} eq 'fatal') {
535			$err->throw;
536			print "This text never printed";
537			## Otherwise warning only
538			} else {
539			warn $err->stringify;
540			print "This text IS printed";
541			}
542			}</pre>
543			<p>
544			</p>
545			<hr />
546			<h1><a name="see_also">SEE ALSO</a></h1>
547			<p><em>Error</em></p>
548			<p><a href="../../../Message/DOM/DOMException.html">the Message::DOM::DOMException manpage</a></p>
549			<p><a href="../../../Message/DOM/DOMError.html">the Message::DOM::DOMError manpage</a></p>
550			<p>
551			</p>
552			<hr />
553			<h1><a name="author">AUTHOR</a></h1>
554			<p>Wakaba <<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>></p>
555			<p>
556			</p>
557			<hr />
558			<h1><a name="license">LICENSE</a></h1>
559			<p>Copyright 2003-2007 Wakaba <<a href="mailto:w@suika.fam.cx">w@suika.fam.cx</a>></p>
560			<p>This program is free software; you can redistribute it and/or
561			modify it under the same terms as Perl itself.</p>
562
563			</body>
564
565			</html>