local-lib5/man/man3/XML::LibXML::Common.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "XML::LibXML::Common 3"
 127 .TH XML::LibXML::Common 3 "2009-10-07" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 XML::LibXML::Common \- Constants and Character Encoding Routines
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 1
 137 \&  use XML::LibXML::Common;
 138 \&
 139 \&  $encodedstring = encodeToUTF8( $name_of_encoding, $sting_to_encode );
 140 \&  $decodedstring = decodeFromUTF8($name_of_encoding, $string_to_decode );
 141 .Ve
 142 .SH "DESCRIPTION"
 143 .IX Header "DESCRIPTION"
 144 XML::LibXML::Common defines constants for all node types and provides interface
 145 to libxml2 charset conversion functions.
 146 .PP
 147 Since XML::LibXML use their own node type definitions, one may want to use
 148 XML::LibXML::Common in its compatibility mode:
 149 .SS "Exporter \s-1TAGS\s0"
 150 .IX Subsection "Exporter TAGS"
 151 .Vb 1
 152 \&  use XML::LibXML::Common qw(:libxml);
 153 .Ve
 154 .PP
 155 \&\f(CW\*(C`:libxml\*(C'\fR tag will use the XML::LibXML Compatibility mode, which defines the old '\s-1XML_\s0'
 156 node-type definitions.
 157 .PP
 158 .Vb 1
 159 \&  use XML::LibXML::Common qw(:gdome);
 160 .Ve
 161 .PP
 162 \&\f(CW\*(C`:gdome\*(C'\fR tag will use the \s-1XML::GDOME\s0 Compatibility mode, which defines the old '\s-1GDOME_\s0'
 163 node-type definitions.
 164 .PP
 165 .Vb 1
 166 \&  use XML::LibXML::Common qw(:w3c);
 167 .Ve
 168 .PP
 169 This uses the nodetype definition names as specified for \s-1DOM\s0.
 170 .PP
 171 .Vb 1
 172 \&  use XML::LibXML::Common qw(:encoding);
 173 .Ve
 174 .PP
 175 This tag can be used to export only the charset encoding functions of
 176 XML::LibXML::Common.
 177 .SS "Exports"
 178 .IX Subsection "Exports"
 179 By default the W3 definitions as defined in the \s-1DOM\s0 specifications and the
 180 encoding functions are exported by XML::LibXML::Common.
 181 .SS "Encoding functions"
 182 .IX Subsection "Encoding functions"
 183 To encode or decode a string to or from \s-1UTF\-8\s0, XML::LibXML::Common exports two
 184 functions, which provide interfact to the encoding support in \f(CW\*(C`libxml2\*(C'\fR. Which encodings are supported by these functions depends on how \f(CW\*(C`libxml2\*(C'\fR was compiled. \s-1UTF\-16\s0 is always supported and on most installations, \s-1ISO\s0
 185 encodings are supported as well.
 186 .PP
 187 This interface was useful for older versions of Perl. Since Perl >= 5.8
 188 provides similar funcions via the \f(CW\*(C`Encode\*(C'\fR module, it is probably a good idea to use those instead.
 189 .IP "encodeToUTF8" 4
 190 .IX Item "encodeToUTF8"
 191 .Vb 1
 192 \&  $encodedstring = encodeToUTF8( $name_of_encoding, $sting_to_encode );
 193 .Ve
 194 .Sp
 195 The function will convert a byte string from the specified encoding to an \s-1UTF\-8\s0
 196 encoded character string.
 197 .IP "decodeToUTF8" 4
 198 .IX Item "decodeToUTF8"
 199 .Vb 1
 200 \&  $decodedstring = decodeFromUTF8($name_of_encoding, $string_to_decode );
 201 .Ve
 202 .Sp
 203 This function converts an \s-1UTF\-8\s0 encoded character string to a specified
 204 encoding. Note that the conversion can raise an error if the given string
 205 contains characters that cannot be represented in the target encoding.
 206 .PP
 207 Both these functions report their errors on the standard error. If an error
 208 occours the function will \fIcroak()\fR. To catch the error information it is
 209 required to call the encoding function from within an eval block in order to
 210 prevent the entire script from being stopped on encoding error.
 211 .SS "A note on history"
 212 .IX Subsection "A note on history"
 213 Before XML::LibXML 1.70, this class was available as a separate \s-1CPAN\s0
 214 distribution, intended to provide functionality shared between XML::LibXML,
 215 \&\s-1XML::GDOME\s0, and possibly other modules. Since there seems to be no progress in
 216 this direction, we decided to merge XML::LibXML::Common 0.13 and XML::LibXML
 217 1.70 to one \s-1CPAN\s0 distribution.
 218 .PP
 219 The merge also naturally eliminates a practical and urgent problem experienced
 220 by many XML::LibXML users on certain platforms, namely misterious misbehavior
 221 of XML::LibXML occurring if the installed (often pre-packaged) version of
 222 XML::LibXML::Common was compiled against an older version of libxml2 than
 223 XML::LibXML.
 224 .SH "AUTHORS"
 225 .IX Header "AUTHORS"
 226 Matt Sergeant,
 227 Christian Glahn,
 228 Petr Pajas
 229 .SH "VERSION"
 230 .IX Header "VERSION"
 231 1.70
 232 .SH "COPYRIGHT"
 233 .IX Header "COPYRIGHT"
 234 2001\-2007, AxKit.com Ltd.
 235 .PP
 236 2002\-2006, Christian Glahn.
 237 .PP
 238 2006\-2009, Petr Pajas.