.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{
.    if \nF \{
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "XML::LibXML::Error 3"
.TH XML::LibXML::Error 3 "2016-07-24" "perl v5.16.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
XML::LibXML::Error \- Structured Errors
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 8
\&  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();
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The XML::LibXML::Error class is a tiny frontend to \fIlibxml2\fR'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.
.PP
Unlike most other XML::LibXML objects, XML::LibXML::Error doesn't wrap an
underlying \fIlibxml2\fR 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
$@\->\fIfield()\fR (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).
.ie n .IP "$XML::LibXML::Error::WARNINGS" 4
.el .IP "\f(CW$XML::LibXML::Error::WARNINGS\fR" 4
.IX Item "$XML::LibXML::Error::WARNINGS"
.Vb 1
\&  $XML::LibXML::Error::WARNINGS=1;
.Ve
.Sp
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 \f(CW\*(C`warn\*(C'\fR and to 2 to report hem via \f(CW\*(C`die\*(C'\fR.
.IP "as_string" 4
.IX Item "as_string"
.Vb 1
\&  $message = $@\->as_string();
.Ve
.Sp
This function serializes an XML::LibXML::Error object to a string containing
the full error message close to the message produced by \fIlibxml2\fR 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 $@).
.IP "dump" 4
.IX Item "dump"
.Vb 1
\&  print $@\->dump();
.Ve
.Sp
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'.
.IP "domain" 4
.IX Item "domain"
.Vb 1
\&  $error_domain = $@\->domain();
.Ve
.Sp
Returns string containing information about what part of the library raised the
error. Can be one of: \*(L"parser\*(R", \*(L"tree\*(R", \*(L"namespace\*(R", \*(L"validity\*(R", \*(L"\s-1HTML\s0 parser\*(R",
\&\*(L"memory\*(R", \*(L"output\*(R", \*(L"I/O\*(R", \*(L"ftp\*(R", \*(L"http\*(R", \*(L"XInclude\*(R", \*(L"XPath\*(R", \*(L"xpointer\*(R",
\&\*(L"regexp\*(R", \*(L"Schemas datatype\*(R", \*(L"Schemas parser\*(R", \*(L"Schemas validity\*(R", \*(L"Relax-NG
parser\*(R", \*(L"Relax-NG validity\*(R", \*(L"Catalog\*(R", \*(L"C14N\*(R", \*(L"\s-1XSLT\*(R", \s0\*(L"validity\*(R".
.IP "code" 4
.IX Item "code"
.Vb 1
\&  $error_code = $@\->code();
.Ve
.Sp
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.
.IP "message" 4
.IX Item "message"
.Vb 1
\&  $error_message = $@\->message();
.Ve
.Sp
Returns a human-readable informative error message.
.IP "level" 4
.IX Item "level"
.Vb 1
\&  $error_level = $@\->level();
.Ve
.Sp
Returns an integer value describing how consequent is the error.
XML::LibXML::Error defines the following constants:
.RS 4
.IP "\(bu" 4
\&\s-1XML_ERR_NONE\s0 = 0
.IP "\(bu" 4
\&\s-1XML_ERR_WARNING\s0 = 1 : A simple warning.
.IP "\(bu" 4
\&\s-1XML_ERR_ERROR\s0 = 2 : A recoverable error.
.IP "\(bu" 4
\&\s-1XML_ERR_FATAL\s0 = 3 : A fatal error.
.RE
.RS 4
.RE
.IP "file" 4
.IX Item "file"
.Vb 1
\&  $filename = $@\->file();
.Ve
.Sp
Returns the filename of the file being processed while the error occurred.
.IP "line" 4
.IX Item "line"
.Vb 1
\&  $line = $@\->line();
.Ve
.Sp
The line number, if available.
.IP "nodename" 4
.IX Item "nodename"
.Vb 1
\&  $nodename = $@\->nodename();
.Ve
.Sp
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.
.IP "str1" 4
.IX Item "str1"
.Vb 1
\&  $error_str1 = $@\->str1();
.Ve
.Sp
Error specific. Extra string information.
.IP "str2" 4
.IX Item "str2"
.Vb 1
\&  $error_str2 = $@\->str2();
.Ve
.Sp
Error specific. Extra string information.
.IP "str3" 4
.IX Item "str3"
.Vb 1
\&  $error_str3 = $@\->str3();
.Ve
.Sp
Error specific. Extra string information.
.IP "num1" 4
.IX Item "num1"
.Vb 1
\&  $error_num1 = $@\->num1();
.Ve
.Sp
Error specific. Extra numeric information.
.IP "num2" 4
.IX Item "num2"
.Vb 1
\&  $error_num2 = $@\->num2();
.Ve
.Sp
In recent libxml2 versions, this value contains a column number of the error or
0 if N/A.
.IP "context" 4
.IX Item "context"
.Vb 1
\&  $string = $@\->context();
.Ve
.Sp
For parsing errors, this field contains about 80 characters of the \s-1XML\s0 near the
place where the error occurred. The field \f(CW\*(C`$@\->column()\*(C'\fR contains the corresponding offset. Where N/A, the field is undefined.
.IP "column" 4
.IX Item "column"
.Vb 1
\&  $offset = $@\->column();
.Ve
.Sp
See \f(CW\*(C`$@\->column()\*(C'\fR above.
.IP "_prev" 4
.IX Item "_prev"
.Vb 1
\&  $previous_error = $@\->_prev();
.Ve
.Sp
This field can possibly hold a reference to another XML::LibXML::Error object
representing an error which occurred just before this error.
.SH "AUTHORS"
.IX Header "AUTHORS"
Matt Sergeant,
Christian Glahn,
Petr Pajas
.SH "VERSION"
.IX Header "VERSION"
2.0128
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
2001\-2007, AxKit.com Ltd.
.PP
2002\-2006, Christian Glahn.
.PP
2006\-2009, Petr Pajas.
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.