| 1 |
README file for Perl extension XML::SAX::ExpatXS |
| 2 |
================================================ |
| 3 |
|
| 4 |
1. Introduction |
| 5 |
2. Dependencies |
| 6 |
3. Installation |
| 7 |
4. Callbacks |
| 8 |
5. Encoding |
| 9 |
|
| 10 |
|
| 11 |
1.Introduction |
| 12 |
------------------------------ |
| 13 |
|
| 14 |
This module is a direct XS implementation of Perl SAX parser |
| 15 |
using Expat. XML::SAX::Expat is implemented as a layer over |
| 16 |
XML::Parser. |
| 17 |
|
| 18 |
The first version of this module has been created by Matt |
| 19 |
Sergeant reusing sources of XML::Parser. The current maintainer |
| 20 |
is Petr Cimprich <petr AT gingerall DOT cz>. |
| 21 |
|
| 22 |
The wrapper is considered stable. Feedback of any kind is |
| 23 |
appreciated. |
| 24 |
|
| 25 |
|
| 26 |
2. Dependencies |
| 27 |
------------------------------ |
| 28 |
|
| 29 |
This module requires Expat XML parser. XML::SAX::ExpatXS 1.10 |
| 30 |
or higher requires Expat 1.95.4 or higher (because |
| 31 |
of XML_SetSkippedEntityHandler). For older Expat versions, it |
| 32 |
is recommended to use XML::SAX::ExpatXS 1.09. |
| 33 |
|
| 34 |
You can download Expat from: http://expat.sourceforge.net/ |
| 35 |
|
| 36 |
Required Perl modules are: |
| 37 |
|
| 38 |
XML::NamespaceSupport |
| 39 |
XML::SAX |
| 40 |
|
| 41 |
|
| 42 |
3. Installation |
| 43 |
------------------------------ |
| 44 |
|
| 45 |
perl Makefile.PL |
| 46 |
make |
| 47 |
make test |
| 48 |
make install |
| 49 |
|
| 50 |
You will need a C compiler to build this module from sources. Other |
| 51 |
option is to install a binary PPM package. |
| 52 |
|
| 53 |
Expat must be installed prior to building XML::SAX::ExpatXS. |
| 54 |
If expat is installed, but in a non-standard directory, then use |
| 55 |
the following options to Makefile.PL: |
| 56 |
|
| 57 |
EXPATLIBPATH=... To set the directory in which to find libexpat |
| 58 |
|
| 59 |
EXPATINCPATH=... To set the directory in which to find expat.h |
| 60 |
|
| 61 |
For example: |
| 62 |
|
| 63 |
perl Makefile.PL EXPATLIBPATH=/home/me/lib EXPATINCPATH=/home/me/include |
| 64 |
|
| 65 |
Note that if you build against a shareable library in a non-standard |
| 66 |
location you may (on some platforms) also have to set your LD_LIBRARY_PATH |
| 67 |
environment variable at run time for perl to find the library. On Windows, |
| 68 |
you have to set your PATH environment variable. |
| 69 |
|
| 70 |
|
| 71 |
4. Callbacks |
| 72 |
------------------------------ |
| 73 |
|
| 74 |
These Perl SAX callbacks are supported and tested: |
| 75 |
|
| 76 |
start_document() |
| 77 |
end_document() |
| 78 |
start_element() |
| 79 |
end_element() |
| 80 |
characters() |
| 81 |
processing_instruction() |
| 82 |
start_prefix_mapping() |
| 83 |
end_prefix_mapping() |
| 84 |
set_document_locator() |
| 85 |
fatal_error() |
| 86 |
comment() |
| 87 |
start_dtd() |
| 88 |
end_dtd() |
| 89 |
start_cdata() |
| 90 |
end_cdata() |
| 91 |
element_decl |
| 92 |
attribute_decl |
| 93 |
notation_decl() |
| 94 |
unparsed_entity_decl() |
| 95 |
external_entity_decl() |
| 96 |
internal_entity_decl() |
| 97 |
start_entity() |
| 98 |
end_entity () |
| 99 |
resolve_entity() |
| 100 |
skipped_entity() |
| 101 |
|
| 102 |
These methods are never called by XML::SAX::ExpatXS: |
| 103 |
|
| 104 |
warning() |
| 105 |
error() |
| 106 |
ignorable_whitespace() |
| 107 |
|
| 108 |
This one is deprecated but it works with XML::SAX::ExpatXS: |
| 109 |
|
| 110 |
xml_decl() |
| 111 |
|
| 112 |
|
| 113 |
5. Encoding |
| 114 |
------------------------------ |
| 115 |
|
| 116 |
These charsets and encodings are supported: |
| 117 |
|
| 118 |
UTF-8 (1) |
| 119 |
UTF-16 (1) |
| 120 |
US-ASCII (1) |
| 121 |
ISO-8859-1 (1) |
| 122 |
ISO-8859-2 (2) |
| 123 |
ISO-8859-3 (2) |
| 124 |
ISO-8859-4 (2) |
| 125 |
ISO-8859-5 (2) |
| 126 |
ISO-8859-7 (2) |
| 127 |
ISO-8859-8 (2) |
| 128 |
ISO-8859-9 (2) |
| 129 |
WINDOWS-1250 (2) |
| 130 |
WINDOWS-1252 (2) |
| 131 |
BIG5 (2) |
| 132 |
EUC-KR (2) |
| 133 |
EUC-JP (2,3) |
| 134 |
Shift JIS. (2,3) |
| 135 |
|
| 136 |
(1) Expat built-in |
| 137 |
(2) external handler |
| 138 |
(3) see lib/XML/SAX/ExpatXS/Encodings/Japanese_Encodings.msg |
| 139 |
|
| 140 |
Other encodings can be added with XML::Encoding, see |
| 141 |
lib/XML/SAX/ExpatXS/Encodings/README for more info. |