1XML::LibXML::Error(3) User Contributed Perl DocumentationXML::LibXML::Error(3)
2
3
4

NAME

6       XML::LibXML::Error - Structured Errors
7

SYNOPSIS

9         eval { ... };
10                 if (ref($@)) {
11                   # handle a structured error (XML::LibXML::Error object)
12                 } elsif ($@) {
13                   # error, but not an XML::LibXML::Error object
14                 } else {
15                   # no error
16                 }
17
18         $XML::LibXML::Error::WARNINGS=1;
19         $message = $@->as_string();
20         print $@->dump();
21         $error_domain = $@->domain();
22         $error_code = $@->code();
23         $error_message = $@->message();
24         $error_level = $@->level();
25         $filename = $@->file();
26         $line = $@->line();
27         $nodename = $@->nodename();
28         $error_str1 = $@->str1();
29         $error_str2 = $@->str2();
30         $error_str3 = $@->str3();
31         $error_num1 = $@->num1();
32         $error_num2 = $@->num2();
33         $string = $@->context();
34         $offset = $@->column();
35         $previous_error = $@->_prev();
36

DESCRIPTION

38       The XML::LibXML::Error class is a tiny frontend to libxml2's structured
39       error support. If XML::LibXML is compiled with structured error
40       support, all errors reported by libxml2 are transformed to
41       XML::LibXML::Error objects. These objects automatically serialize to
42       the corresponding error messages when printed or used in a string
43       operation, but as objects, can also be used to get a detailed and
44       structured information about the error that occurred.
45
46       Unlike most other XML::LibXML objects, XML::LibXML::Error doesn't wrap
47       an underlying libxml2 structure directly, but rather transforms it to a
48       blessed Perl hash reference containing the individual fields of the
49       structured error information as hash key-value pairs. Individual items
50       (fields) of a structured error can either be obtained directly as
51       $@->{field}, or using autoloaded methods such as as $@->field() (where
52       field is the field name). XML::LibXML::Error objects have the following
53       fields: domain, code, level, file, line, nodename, message, str1, str2,
54       str3, num1, num2, and _prev (some of them may be undefined).
55
56       $XML::LibXML::Error::WARNINGS
57             $XML::LibXML::Error::WARNINGS=1;
58
59           Traditionally, XML::LibXML was suppressing parser warnings by
60           setting libxml2's global variable xmlGetWarningsDefaultValue to 0.
61           Since 1.70 we do not change libxml2's global variables anymore; for
62           backward compatibility, XML::LibXML suppresses warnings. This
63           variable can be set to 1 to enable reporting of these warnings via
64           Perl "warn" and to 2 to report hem via "die".
65
66       as_string
67             $message = $@->as_string();
68
69           This function serializes an XML::LibXML::Error object to a string
70           containing the full error message close to the message produced by
71           libxml2 default error handlers and tools like xmllint. This method
72           is also used to overload "" operator on XML::LibXML::Error, so it
73           is automatically called whenever XML::LibXML::Error object is
74           treated as a string (e.g. in print $@).
75
76       dump
77             print $@->dump();
78
79           This function serializes an XML::LibXML::Error to a string
80           displaying all fields of the error structure individually on
81           separate lines of the form 'name' => 'value'.
82
83       domain
84             $error_domain = $@->domain();
85
86           Returns string containing information about what part of the
87           library raised the error. Can be one of: "parser", "tree",
88           "namespace", "validity", "HTML parser", "memory", "output", "I/O",
89           "ftp", "http", "XInclude", "XPath", "xpointer", "regexp", "Schemas
90           datatype", "Schemas parser", "Schemas validity", "Relax-NG parser",
91           "Relax-NG validity", "Catalog", "C14N", "XSLT", "validity".
92
93       code
94             $error_code = $@->code();
95
96           Returns the actual libxml2 error code. The XML::LibXML::ErrNo
97           module defines constants for individual error codes. Currently
98           libxml2 uses over 480 different error codes.
99
100       message
101             $error_message = $@->message();
102
103           Returns a human-readable informative error message.
104
105       level
106             $error_level = $@->level();
107
108           Returns an integer value describing how consequent is the error.
109           XML::LibXML::Error defines the following constants:
110
111           ·   XML_ERR_NONE = 0
112
113           ·   XML_ERR_WARNING = 1 : A simple warning.
114
115           ·   XML_ERR_ERROR = 2 : A recoverable error.
116
117           ·   XML_ERR_FATAL = 3 : A fatal error.
118
119       file
120             $filename = $@->file();
121
122           Returns the filename of the file being processed while the error
123           occurred.
124
125       line
126             $line = $@->line();
127
128           The line number, if available.
129
130       nodename
131             $nodename = $@->nodename();
132
133           Name of the node where error occurred, if available. When this
134           field is non-empty, libxml2 actually returned a physical pointer to
135           the specified node.  Due to memory management issues, it is very
136           difficult to implement a way to expose the pointer to the Perl
137           level as a XML::LibXML::Node. For this reason, XML::LibXML::Error
138           currently only exposes the name the node.
139
140       str1
141             $error_str1 = $@->str1();
142
143           Error specific. Extra string information.
144
145       str2
146             $error_str2 = $@->str2();
147
148           Error specific. Extra string information.
149
150       str3
151             $error_str3 = $@->str3();
152
153           Error specific. Extra string information.
154
155       num1
156             $error_num1 = $@->num1();
157
158           Error specific. Extra numeric information.
159
160       num2
161             $error_num2 = $@->num2();
162
163           In recent libxml2 versions, this value contains a column number of
164           the error or 0 if N/A.
165
166       context
167             $string = $@->context();
168
169           For parsing errors, this field contains about 80 characters of the
170           XML near the place where the error occurred. The field
171           "$@->column()" contains the corresponding offset. Where N/A, the
172           field is undefined.
173
174       column
175             $offset = $@->column();
176
177           See "$@->column()" above.
178
179       _prev
180             $previous_error = $@->_prev();
181
182           This field can possibly hold a reference to another
183           XML::LibXML::Error object representing an error which occurred just
184           before this error.
185

AUTHORS

187       Matt Sergeant, Christian Glahn, Petr Pajas
188

VERSION

190       2.0018
191
193       2001-2007, AxKit.com Ltd.
194
195       2002-2006, Christian Glahn.
196
197       2006-2009, Petr Pajas.
198
199
200
201perl v5.16.3                      2013-05-13             XML::LibXML::Error(3)
Impressum