++ed by:
XLAT MJEMMESON CONTRA MIROD MJGARDNER

55 PAUSE users
35 non-PAUSE users.

Author image Petr Pajas
and 1 contributors

NAME

XML::LibXML::Error - Structured Errors

SYNOPSIS

  eval { ... };
          if (ref($@)) {
            # handle a structured error (XML::LibXML::Error object)
          } elsif ($@) {
            # error, but not an XML::LibXML::Error object
          } else {
            # no error
          }

  $message = $@->as_string();
  print $@->dump();
  $error_domain = $@->domain();
  $error_code = $@->code();
  $error_message = $@->message();
  $error_level = $@->level();
  $filename = $@->file();
  $line = $@->line();
  $nodename = $@->nodename();
  $error_str1 = $@->str1();
  $error_str2 = $@->str2();
  $error_str3 = $@->str3();
  $error_int1 = $@->int1();
  $error_int2 = $@->int2();
  $previous_error = $@->_prev();

DESCRIPTION

The XML::LibXML::Error class is a tiny frontend to libxml2'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.

Unlike most other XML::LibXML objects, XML::LibXML::Error doesn't wrap an underlying libxml2 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 $@->{field}, or using autoloaded methods such as as $@->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).

as_string
  $message = $@->as_string();

This functions takes serializes a XML::LibXML::Error object to a string containing the full error message close to the message produced by libxml2 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 $@).

dump
  print $@->dump();

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'.

domain
  $error_domain = $@->domain();

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".

code
  $error_code = $@->code();

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.

message
  $error_message = $@->message();

Returns a human-readable informative error message.

level
  $error_level = $@->level();

Returns an integer value describing how consequent is the error. XML::LibXML::Error defines the following constants:

  • XML_ERR_NONE = 0

  • XML_ERR_WARNING = 1 : A simple warning.

  • XML_ERR_ERROR = 2 : A recoverable error.

  • XML_ERR_FATAL = 3 : A fatal error.

file
  $filename = $@->file();

Returns the filename of the file being processed while the error occurred.

line
  $line = $@->line();

The line number, if available.

nodename
  $nodename = $@->nodename();

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.

str1
  $error_str1 = $@->str1();

Error specific. Extra string information.

str2
  $error_str2 = $@->str2();

Error specific. Extra string information.

str3
  $error_str3 = $@->str3();

Error specific. Extra string information.

int1
  $error_int1 = $@->int1();

Error specific. Extra numeric information.

int2
  $error_int2 = $@->int2();

Error specific. Extra numeric information.

_prev
  $previous_error = $@->_prev();

This field can possibly hold a reference to another XML::LibXML::Error object representing an error which occurred just before this error.

AUTHORS

Matt Sergeant, Christian Glahn, Petr Pajas

VERSION

1.66

COPYRIGHT

2001-2007, AxKit.com Ltd; 2002-2006 Christian Glahn; 2006-2008 Petr Pajas, All rights reserved.