/perl/vendor/lib/XML/LibXML/Error.pod
Unknown | 257 lines | 144 code | 113 blank | 0 comment | 0 complexity | 8fa17d8e2d52939fc89473a75b40e050 MD5 | raw file
Possible License(s): LGPL-3.0, Unlicense, GPL-2.0, LGPL-2.0, BSD-3-Clause, LGPL-2.1, AGPL-1.0, GPL-3.0
- =head1 NAME
- XML::LibXML::Error - Structured Errors
- =head1 SYNOPSIS
- eval { ... };
- if (ref($@)) {
- # handle a structured error (XML::LibXML::Error object)
- } elsif ($@) {
- # error, but not an XML::LibXML::Error object
- } else {
- # no error
- }
- $XML::LibXML::Error::WARNINGS=1;
- $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_num1 = $@->num1();
- $error_num2 = $@->num2();
- $string = $@->context();
- $offset = $@->column();
- $previous_error = $@->_prev();
- =head1 DESCRIPTION
- The XML::LibXML::Error class is a tiny frontend to I<<<<<< libxml2 >>>>>>'s structured error support. If XML::LibXML is compiled 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 I<<<<<< 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, num1, num2, and _prev (some of them may be undefined).
- =over 4
- =item $XML::LibXML::Error::WARNINGS
- $XML::LibXML::Error::WARNINGS=1;
- Traditionally, XML::LibXML was suppressing parser warnings by setting libxml2's
- global variable xmlGetWarningsDefaultValue to 0. Since 1.70 we do not change
- libxml2's global variables anymore; for backward compatibility, XML::LibXML
- suppresses warnings. This variable can be set to 1 to enable reporting of these
- warnings via Perl C<<<<<< warn >>>>>> and to 2 to report hem via C<<<<<< die >>>>>>.
- =item as_string
- $message = $@->as_string();
- This function serializes an XML::LibXML::Error object to a string containing
- the full error message close to the message produced by I<<<<<< 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 $@).
- =item dump
- print $@->dump();
- This function serializes an XML::LibXML::Error to a string displaying all
- fields of the error structure individually on separate lines of the form 'name'
- => 'value'.
- =item 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".
- =item 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.
- =item message
- $error_message = $@->message();
- Returns a human-readable informative error message.
- =item level
- $error_level = $@->level();
- Returns an integer value describing how consequent is the error.
- XML::LibXML::Error defines the following constants:
- =over 4
- =item *
- XML_ERR_NONE = 0
- =item *
- XML_ERR_WARNING = 1 : A simple warning.
- =item *
- XML_ERR_ERROR = 2 : A recoverable error.
- =item *
- XML_ERR_FATAL = 3 : A fatal error.
- =back
- =item file
- $filename = $@->file();
- Returns the filename of the file being processed while the error occurred.
- =item line
- $line = $@->line();
- The line number, if available.
- =item 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.
- =item str1
- $error_str1 = $@->str1();
- Error specific. Extra string information.
- =item str2
- $error_str2 = $@->str2();
- Error specific. Extra string information.
- =item str3
- $error_str3 = $@->str3();
- Error specific. Extra string information.
- =item num1
- $error_num1 = $@->num1();
- Error specific. Extra numeric information.
- =item num2
- $error_num2 = $@->num2();
- In recent libxml2 versions, this value contains a column number of the error or
- 0 if N/A.
- =item context
- $string = $@->context();
- For parsing errors, this field contains about 80 characters of the XML near the
- place where the error occurred. The field C<<<<<< $@->column() >>>>>> contains the corresponding offset. Where N/A, the field is undefined.
- =item column
- $offset = $@->column();
- See C<<<<<< $@->column() >>>>>> above.
- =item _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.
- =back
- =head1 AUTHORS
- Matt Sergeant,
- Christian Glahn,
- Petr Pajas
- =head1 VERSION
- 1.88
- =head1 COPYRIGHT
- 2001-2007, AxKit.com Ltd.
- 2002-2006, Christian Glahn.
- 2006-2009, Petr Pajas.
- =cut