/usr/lib/perl5/XML/LibXML/Error.pod is in libxml-libxml-perl 1.89+dfsg-1ubuntu0.1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 | =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.89
=head1 COPYRIGHT
2001-2007, AxKit.com Ltd.
2002-2006, Christian Glahn.
2006-2009, Petr Pajas.
=cut
|