Commit | Line | Data |
3fea05b9 |
1 | =head1 NAME |
2 | |
3 | XML::LibXML::Error - Structured Errors |
4 | |
5 | =head1 SYNOPSIS |
6 | |
7 | |
8 | |
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 | |
37 | =head1 DESCRIPTION |
38 | |
39 | The XML::LibXML::Error class is a tiny frontend to I<<<<<< libxml2 >>>>>>'s structured error support. If XML::LibXML is compied with structured error |
40 | support, all errors reported by libxml2 are transformed to XML::LibXML:Error |
41 | objects. These objects automatically serialize to the corresponding error |
42 | messages when printed or used in a string operation, but as objects, can also |
43 | be used to get a detailed and structured information about the error that |
44 | occurred. |
45 | |
46 | Unlike most other XML::LibXML objects, XML::LibXML::Error doesn't wrap an |
47 | underlying I<<<<<< libxml2 >>>>>> structure directly, but rather transforms it to a blessed Perl hash reference |
48 | containing the individual fields of the structured error information as hash |
49 | key-value pairs. Individual items (fields) of a structured error can either be |
50 | obtained directly as $@->{field}, or using autoloaded methods such as as |
51 | $@->field() (where field is the field name). XML::LibXML::Error objects have |
52 | the following fields: domain, code, level, file, line, nodename, message, str1, |
53 | str2, str3, num1, num2, and _prev (some of them may be undefined). |
54 | |
55 | =over 4 |
56 | |
57 | =item $XML::LibXML::Error::WARNINGS |
58 | |
59 | $XML::LibXML::Error::WARNINGS=1; |
60 | |
61 | Traditionally, XML::LibXML was supressing parser warnings by setting libxml2's |
62 | global variable xmlGetWarningsDefaultValue to 0. Since 1.70 we do not change |
63 | libxml2's global variables anymore; for backward compatibility, XML::LibXML |
64 | suppresses warnings. This variable can be set to 1 to enable reporting of these |
65 | warnings via Perl C<<<<<< warn >>>>>> and to 2 to report hem via C<<<<<< die >>>>>>. |
66 | |
67 | $message = $@->as_string(); |
68 | |
69 | This functions takes serializes a XML::LibXML::Error object to a string |
70 | 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 |
71 | overload "" operator on XML::LibXML::Error, so it is automatically called |
72 | whenever XML::LibXML::Error object is treated as a string (e.g. in print $@). |
73 | |
74 | |
75 | =item dump |
76 | |
77 | print $@->dump(); |
78 | |
79 | This function serializes a XML::LibXML::Error to a string displaying all fields |
80 | of the error structure individually on separate lines of the form 'name' => |
81 | 'value'. |
82 | |
83 | |
84 | =item domain |
85 | |
86 | $error_domain = $@->domain(); |
87 | |
88 | Returns string containing information about what part of the library raised the |
89 | error. Can be one of: "parser", "tree", "namespace", "validity", "HTML parser", |
90 | "memory", "output", "I/O", "ftp", "http", "XInclude", "XPath", "xpointer", |
91 | "regexp", "Schemas datatype", "Schemas parser", "Schemas validity", "Relax-NG |
92 | parser", "Relax-NG validity", "Catalog", "C14N", "XSLT", "validity". |
93 | |
94 | |
95 | =item code |
96 | |
97 | $error_code = $@->code(); |
98 | |
99 | Returns the actual libxml2 error code. The XML::LibXML::ErrNo module defines |
100 | constants for individual error codes. Currently libxml2 uses over 480 different |
101 | error codes. |
102 | |
103 | |
104 | =item message |
105 | |
106 | $error_message = $@->message(); |
107 | |
108 | Returns a human-readable informative error message. |
109 | |
110 | |
111 | =item level |
112 | |
113 | $error_level = $@->level(); |
114 | |
115 | Returns an integer value describing how consequent is the error. |
116 | XML::LibXML::Error defines the following constants: |
117 | |
118 | |
119 | =over 4 |
120 | |
121 | =item * |
122 | |
123 | XML_ERR_NONE = 0 |
124 | |
125 | |
126 | |
127 | =item * |
128 | |
129 | XML_ERR_WARNING = 1 : A simple warning. |
130 | |
131 | |
132 | |
133 | =item * |
134 | |
135 | XML_ERR_ERROR = 2 : A recoverable error. |
136 | |
137 | |
138 | |
139 | =item * |
140 | |
141 | XML_ERR_FATAL = 3 : A fatal error. |
142 | |
143 | |
144 | |
145 | =back |
146 | |
147 | |
148 | =item file |
149 | |
150 | $filename = $@->file(); |
151 | |
152 | Returns the filename of the file being processed while the error occurred. |
153 | |
154 | |
155 | =item line |
156 | |
157 | $line = $@->line(); |
158 | |
159 | The line number, if available. |
160 | |
161 | |
162 | =item nodename |
163 | |
164 | $nodename = $@->nodename(); |
165 | |
166 | Name of the node where error occurred, if available. When this field is |
167 | non-empty, libxml2 actually returned a physical pointer to the specified node. |
168 | Due to memory management issues, it is very difficult to implement a way to |
169 | expose the pointer to the Perl level as a XML::LibXML::Node. For this reason, |
170 | XML::LibXML::Error currently only exposes the name the node. |
171 | |
172 | |
173 | =item str1 |
174 | |
175 | $error_str1 = $@->str1(); |
176 | |
177 | Error specific. Extra string information. |
178 | |
179 | |
180 | =item str2 |
181 | |
182 | $error_str2 = $@->str2(); |
183 | |
184 | Error specific. Extra string information. |
185 | |
186 | |
187 | =item str3 |
188 | |
189 | $error_str3 = $@->str3(); |
190 | |
191 | Error specific. Extra string information. |
192 | |
193 | |
194 | =item num1 |
195 | |
196 | $error_num1 = $@->num1(); |
197 | |
198 | Error specific. Extra numeric information. |
199 | |
200 | |
201 | =item num2 |
202 | |
203 | $error_num2 = $@->num2(); |
204 | |
205 | In recent libxml2 versions, this value contains a column number of the error or |
206 | 0 if N/A. |
207 | |
208 | |
209 | =item context |
210 | |
211 | $string = $@->context(); |
212 | |
213 | For parsing errors, this field contains about 80 characters of the XML near the |
214 | place where the error occurred. The field C<<<<<< $@->column() >>>>>> contains the corresponding offset. Where N/A, the field is undefined. |
215 | |
216 | |
217 | =item column |
218 | |
219 | $offset = $@->column(); |
220 | |
221 | See C<<<<<< $@->column() >>>>>> above. |
222 | |
223 | |
224 | =item _prev |
225 | |
226 | $previous_error = $@->_prev(); |
227 | |
228 | This field can possibly hold a reference to another XML::LibXML::Error object |
229 | representing an error which occurred just before this error. |
230 | |
231 | |
232 | |
233 | =back |
234 | |
235 | =head1 AUTHORS |
236 | |
237 | Matt Sergeant, |
238 | Christian Glahn, |
239 | Petr Pajas |
240 | |
241 | |
242 | =head1 VERSION |
243 | |
244 | 1.70 |
245 | |
246 | =head1 COPYRIGHT |
247 | |
248 | 2001-2007, AxKit.com Ltd. |
249 | |
250 | 2002-2006, Christian Glahn. |
251 | |
252 | 2006-2009, Petr Pajas. |
253 | |
254 | =cut |