Commits

pa...@9ae0c189-cd1f-4510-a509-f4891f5cf20d  committed 57eb8c1

added documentation for Error and ErrNo modules

  • Participants
  • Parent commits 2489391
  • Branches structerror

Comments (0)

Files changed (1)

File example/libxml.dkb

       <varlistentry>
         <term>toStringC14N</term>
         <listitem>
-          <para><funcsynopsis><funcsynopsisinfo>$c14nstr = $doc-&#62;toStringC14N($comment_flag,$xpath); </funcsynopsisinfo></funcsynopsis>A
-          variation to toString, that returns the canonized form of the given
+          <funcsynopsis><funcsynopsisinfo>$c14nstr = $doc-&#62;toStringC14N($comment_flag,$xpath);</funcsynopsisinfo></funcsynopsis>
+          <para>A variation to toString, that returns the canonized form of the given
           document.</para>
         </listitem>
       </varlistentry>
       </varlistentry>
     </variablelist>
   </chapter>
+  <chapter>
+    <title>Structured Errors</title>
+    <titleabbrev>XML::LibXML::Error</titleabbrev> 
+    <sect1>
+      <title>Synopsis</title>
+      <programlisting>
+        eval { ... };
+        if (ref($@)) {
+          # handle a structured error (XML::LibXML::Error object)
+        } elsif ($@) {
+          # error, but not an XML::LibXML::Error object
+        } else {
+          # no error
+        }
+      </programlisting>
+    </sect1>
+    <sect1>
+      <title>Description</title>
+      <para>The
+	XML::LibXML::Error class is a tiny frontend to
+	<emphasis>libxml2</emphasis>&#39;s structured error support. If
+	XML::LibXML is compied with structured error support, all errors
+	reported by libxml2 are transformed to XML::LibXML:Error
+	objects. These objects automatically serialize to the
+	corresponding error messages when printed or used in a string
+	operation, but as objects, can also be used to get a detailed and
+	structured information about the error that occurred.
+      </para>
+      <para>Unlike most other XML::LibXML objects, XML::LibXML::Error
+	doesn't wrap an underlying <emphasis>libxml2</emphasis>
+	structure directly, but rather transforms it to a blessed Perl
+	hash reference containing the individual fields of the
+	structured error information as hash key-value pairs. Individual
+	items (fields) of a structured error can either be
+	obtained directly as $@-&#62;{field}, or using autoloaded
+	methods such as as $@-&#62;field() (where field is the field
+	name). XML::LibXML::Error objects have the following fields:
+	domain, code, level, file, line, nodename, message, str1, str2,
+	str3, int1, int2, and _prev (some of them may be undefined).
+      </para>
+      <variablelist>
+	<varlistentry>
+	  <term>as_string</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$message = $@-&#62;as_string();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>This functions takes serializes a XML::LibXML::Error
+	      object to a string containing the full error message
+	      close to the message produced by <emphasis>libxml2</emphasis> default error
+	      handlers and tools like xmllint. This method is also used
+	      to overload "" operator on XML::LibXML::Error, so it is
+	      automatically called whenever XML::LibXML::Error object
+	      is treated as a string (e.g. in print $@).
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>dump</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>print $@->dump();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>This function serializes a XML::LibXML::Error to a 
+	      string displaying all fields of the error structure
+	      individually on separate lines of the form 'name' => 'value'.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>domain</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$error_domain = $@->domain();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>Returns string containing information about what part
+	      of the library raised the error. Can be one of:
+	      "parser", "tree", "namespace", "validity", "HTML parser",
+	      "memory", "output", "I/O", "ftp", "http",
+	      "XInclude", "XPath", "xpointer", "regexp", "Schemas
+	      datatype", 
+	      "Schemas parser", "Schemas validity",
+	      "Relax-NG parser", "Relax-NG validity", "Catalog",
+	      "C14N", "XSLT", "validity".
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>code</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$error_code = $@->code();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>Returns the actual libxml2 error code.
+	      The XML::LibXML::ErrNo module defines
+	      constants for individual error codes. Currently
+	      libxml2 uses over 480 different error codes.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>message</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$error_message = $@->message();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>Returns a human-readable informative error
+	      message.</para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>level</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$error_level = $@->level();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>Returns an integer value describing how consequent is
+	      the error. XML::LibXML::Error defines the following
+	      constants:
+	    </para>
+	    <itemizedlist>
+	      <listitem>
+		<para>XML_ERR_NONE = 0</para>
+	      </listitem>
+	      <listitem>
+		<para>XML_ERR_WARNING = 1 : A simple warning.</para>
+	      </listitem>
+	      <listitem>
+		<para>XML_ERR_ERROR = 2 : A recoverable error.</para>
+	      </listitem>
+	      <listitem>
+		<para>XML_ERR_FATAL = 3 : A fatal error.</para>
+	      </listitem>
+	    </itemizedlist>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>file</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$filename = $@->file();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>Returns the filename of the file being processed while
+	      the error occurred.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>line</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$line = $@->line();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>The line number, if available.</para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>nodename</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$nodename = $@->nodename();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>Name of the node where error occurred, if available.
+	      When this field is non-empty, libxml2 actually returned a
+	      physical pointer to the specified node. Due to memory
+	      management issues, it is very difficult to implement a
+	      way to expose the pointer to the Perl level as a
+	      XML::LibXML::Node. For this reason, XML::LibXML::Error
+	      currently only exposes the name the node.
+	    </para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>str1</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$error_str1 = $@->str1();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>Error specific. Extra string information.</para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>str2</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$error_str2 = $@->str2();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>Error specific. Extra string information.</para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>str3</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$error_str3 = $@->str3();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>Error specific. Extra string information.</para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>int1</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$error_int1 = $@->int1();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>Error specific. Extra numeric information.</para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>int2</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$error_int2 = $@->int2();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>Error specific. Extra numeric information.</para>
+	  </listitem>
+	</varlistentry>
+	<varlistentry>
+	  <term>_prev</term>
+	  <listitem>
+	    <funcsynopsis>
+	      <funcsynopsisinfo>$previous_error = $@->_prev();</funcsynopsisinfo>
+	    </funcsynopsis>
+	    <para>This field can possibly hold a reference to another
+	      XML::LibXML::Error object representing an error which
+	      occurred just before this error.</para>
+	  </listitem>
+	</varlistentry>
+      </variablelist>
+    </sect1>
+  </chapter>
+  <chapter>
+    <title>Structured Errors</title>
+    <titleabbrev>XML::LibXML::ErrNo</titleabbrev> 
+    <para>This module is based on xmlerror.h libxml2 C header file. 
+       It defines symbolic constants for all libxml2 error codes.
+       Currently libxml2 uses over 480 different error codes.
+       See also XML::LibXML::Error.
+    </para>
+  </chapter>
 </book>