lib/XML/LibXML/Common.pod

   1 =head1 NAME
   2
   3 XML::LibXML::Common - Constants and Character Encoding Routines
   4
   5 =head1 SYNOPSIS
   6
   7
   8
   9   use XML::LibXML::Common;
  10
  11   $encodedstring = encodeToUTF8( $name_of_encoding, $sting_to_encode );
  12   $decodedstring = decodeFromUTF8($name_of_encoding, $string_to_decode );
  13
  14 =head1 DESCRIPTION
  15
  16 XML::LibXML::Common defines constants for all node types and provides interface
  17 to libxml2 charset conversion functions.
  18
  19 Since XML::LibXML use their own node type definitions, one may want to use
  20 XML::LibXML::Common in its compatibility mode:
  21
  22
  23 =head2 Exporter TAGS
  24
  25
  26
  27   use XML::LibXML::Common qw(:libxml);
  28
  29 C<<<<<< :libxml >>>>>> tag will use the XML::LibXML Compatibility mode, which defines the old 'XML_'
  30 node-type definitions.
  31
  32
  33
  34   use XML::LibXML::Common qw(:gdome);
  35
  36 C<<<<<< :gdome >>>>>> tag will use the XML::GDOME Compatibility mode, which defines the old 'GDOME_'
  37 node-type definitions.
  38
  39
  40
  41   use XML::LibXML::Common qw(:w3c);
  42
  43 This uses the nodetype definition names as specified for DOM.
  44
  45
  46
  47   use XML::LibXML::Common qw(:encoding);
  48
  49 This tag can be used to export only the charset encoding functions of
  50 XML::LibXML::Common.
  51
  52
  53 =head2 Exports
  54
  55 By default the W3 definitions as defined in the DOM specifications and the
  56 encoding functions are exported by XML::LibXML::Common.
  57
  58
  59 =head2 Encoding functions
  60
  61 To encode or decode a string to or from UTF-8, XML::LibXML::Common exports two
  62 functions, which provide an interface to the encoding support in C<<<<<< libxml2 >>>>>>. Which encodings are supported by these functions depends on how C<<<<<< libxml2 >>>>>> was compiled. UTF-16 is always supported and on most installations, ISO
  63 encodings are supported as well.
  64
  65 This interface was useful for older versions of Perl. Since Perl >= 5.8
  66 provides similar functions via the C<<<<<< Encode >>>>>> module, it is probably a good idea to use those instead.
  67
  68 =over 4
  69
  70 =item encodeToUTF8
  71
  72   $encodedstring = encodeToUTF8( $name_of_encoding, $sting_to_encode );
  73
  74 The function will convert a byte string from the specified encoding to an UTF-8
  75 encoded character string.
  76
  77
  78 =item decodeToUTF8
  79
  80   $decodedstring = decodeFromUTF8($name_of_encoding, $string_to_decode );
  81
  82 This function converts an UTF-8 encoded character string to a specified
  83 encoding. Note that the conversion can raise an error if the given string
  84 contains characters that cannot be represented in the target encoding.
  85
  86
  87
  88 =back
  89
  90 Both these functions report their errors on the standard error. If an error
  91 occurs the function will croak(). To catch the error information it is required
  92 to call the encoding function from within an eval block in order to prevent the
  93 entire script from being stopped on encoding error.
  94
  95
  96 =head2 A note on history
  97
  98 Before XML::LibXML 1.70, this class was available as a separate CPAN
  99 distribution, intended to provide functionality shared between XML::LibXML,
 100 XML::GDOME, and possibly other modules. Since there seems to be no progress in
 101 this direction, we decided to merge XML::LibXML::Common 0.13 and XML::LibXML
 102 1.70 to one CPAN distribution.
 103
 104 The merge also naturally eliminates a practical and urgent problem experienced
 105 by many XML::LibXML users on certain platforms, namely mysterious misbehavior
 106 of XML::LibXML occurring if the installed (often pre-packaged) version of
 107 XML::LibXML::Common was compiled against an older version of libxml2 than
 108 XML::LibXML.
 109
 110 =head1 AUTHORS
 111
 112 Matt Sergeant,
 113 Christian Glahn,
 114 Petr Pajas
 115
 116
 117 =head1 VERSION
 118
 119 2.0207
 120
 121 =head1 COPYRIGHT
 122
 123 2001-2007, AxKit.com Ltd.
 124
 125 2002-2006, Christian Glahn.
 126
 127 2006-2009, Petr Pajas.
 128
 129 =cut
 130
 131
 132 =head1 LICENSE
 133
 134 This program is free software; you can redistribute it and/or modify it under
 135 the same terms as Perl itself.
 136