diff options
Diffstat (limited to 'Master/tlpkg/tlperl0/lib/XML/LibXML/Error.pod')
-rwxr-xr-x | Master/tlpkg/tlperl0/lib/XML/LibXML/Error.pod | 254 |
1 files changed, 254 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl0/lib/XML/LibXML/Error.pod b/Master/tlpkg/tlperl0/lib/XML/LibXML/Error.pod new file mode 100755 index 00000000000..9583ba5b76f --- /dev/null +++ b/Master/tlpkg/tlperl0/lib/XML/LibXML/Error.pod @@ -0,0 +1,254 @@ +=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 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 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 supressing 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 >>>>>>. + + $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 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 a 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.70 + +=head1 COPYRIGHT + +2001-2007, AxKit.com Ltd. + +2002-2006, Christian Glahn. + +2006-2009, Petr Pajas. + +=cut |