<ppdoc>
<copyright>
Copyright (c) 2001 by Addison Wesley Longman, Inc. This material may
be distributed only subject to the terms and conditions set forth in
the Open Publication License, v1.0 or later (the latest version is
presently available at http://www.opencontent.org/openpub/).
<p/>
Distribution of substantively modified versions of this document is
prohibited without the explicit permission of the copyright holder.
<p/>
Distribution of the work or derivative of the work in any standard
(paper) book form is prohibited unless prior permission is obtained
from the copyright holder.
</copyright>
<class name="Exception" super="Object" type="class" ref="xref-000001">
<p/>
  Descendents of class <classname>Exception</classname> are used to communicate
  between <meth>raise</meth>
  methods and <tt>rescue</tt> statements in <tt>begin/end</tt>
  blocks. <classname>Exception</classname> objects carry information about the
  exception---its type (the exception's class name), an optional
  descriptive string, and optional traceback information.
<p/>
<methods type="class">
        <method name="exception" ref="exception">
      <callseq>
                Exception.exception( <opt><obj>aString</obj></opt> )
        <returns><obj>anException</obj></returns>
      </callseq>
      <desc>
<p/>
      Creates and returns a new exception object, optionally setting the message to 
      <obj>aString</obj>.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
  <methods type="instance">
        <method name="backtrace" ref="backtrace">
      <callseq>
        <obj>exc</obj>.backtrace
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns any backtrace associated with the exception. The
      backtrace is an array of strings, each containing
      either ``filename:lineNo: in `method''' or ``filename:lineNo.''
<p/>
<codefragment>
<alltt><fullcode><![CDATA[         def a
           raise "boom"
         end

         def b
           a()
         end

         begin
           b()
         rescue => detail
#           print detail.backtrace.join("\n")
!-           print detail.backtrace.join("\n").gsub(/-:/, 'prog.rb:')
         end
]]></fullcode>
def<nbsp/>a
<nbsp/><nbsp/>raise<nbsp/>"boom"
end
<p/>
def<nbsp/>b
<nbsp/><nbsp/>a()
end
<p/>
begin
<nbsp/><nbsp/>b()
rescue<nbsp/>=&gt;<nbsp/>detail
<nbsp/><nbsp/>print<nbsp/>detail.backtrace.join("\n")
end
</alltt>
</codefragment>
<em>produces:</em>
<codefragment><alltt>
prog.rb:2:in<nbsp/>`a'
prog.rb:6:in<nbsp/>`b'
prog.rb:10
</alltt>
</codefragment>
<p/>
      </desc>
    </method>
<p/>
        <method name="exception" ref="exception">
      <callseq>
                <obj>exc</obj>.exception( <opt><obj>aString</obj></opt> )
        <returns><obj>anException</obj> or <obj>exc</obj></returns>
      </callseq>
      <desc>
<p/>
      With no argument, returns the receiver. Otherwise, creates a new
      exception object of the same class as the receiver, but with a
      different message.
<p/>
      </desc>
    </method>
<p/>
        <method name="message" ref="message">
      <callseq>
        <obj>exc</obj>.message <returns><obj>aString</obj></returns>
      </callseq>
      <desc>
<p/>
      Returns the message associated with this exception.
<p/>
      </desc>
    </method>
<p/>
        <method name="set_backtrace" ref="set_backtrace">
      <callseq>
                <obj>exc</obj>.set_backtrace( <obj>anArray</obj> )
        <returns><obj>anArray</obj></returns>
      </callseq>
      <desc>
<p/>
      Sets the backtrace information associated with <obj>exc</obj>. The
      argument must be an array of <classname>String</classname> objects in the format
      described in <cim><file>exception</file><front>Exception</front><back>backtrace</back><mref>backtrace</mref></cim>.
<p/>
      </desc>
    </method>
<p/>
  </methods>
<p/>
</class>
</ppdoc>
