local-lib5/lib/perl5/i486-linux-gnu-thread-multi/XML/LibXML/Error.pod

   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