README file for Perl extension XML::SAX::ExpatXS ================================================ 1. Introduction 2. Dependencies 3. Installation 4. Callbacks 5. Encoding 1.Introduction ------------------------------ This module is a direct XS implementation of Perl SAX parser using Expat. XML::SAX::Expat is implemented as a layer over XML::Parser. The first version of this module has been created by Matt Sergeant reusing sources of XML::Parser. The current maintainer is Petr Cimprich . The wrapper is considered stable. Feedback of any kind is appreciated. 2. Dependencies ------------------------------ This module requires Expat XML parser. XML::SAX::ExpatXS 1.10 or higher requires Expat 1.95.4 or higher (because of XML_SetSkippedEntityHandler). For older Expat versions, it is recommended to use XML::SAX::ExpatXS 1.09. You can download Expat from: http://expat.sourceforge.net/ Required Perl modules are: XML::NamespaceSupport XML::SAX 3. Installation ------------------------------ perl Makefile.PL make make test make install You will need a C compiler to build this module from sources. Other option is to install a binary PPM package. Expat must be installed prior to building XML::SAX::ExpatXS. If expat is installed, but in a non-standard directory, then use the following options to Makefile.PL: EXPATLIBPATH=... To set the directory in which to find libexpat EXPATINCPATH=... To set the directory in which to find expat.h For example: perl Makefile.PL EXPATLIBPATH=/home/me/lib EXPATINCPATH=/home/me/include Note that if you build against a shareable library in a non-standard location you may (on some platforms) also have to set your LD_LIBRARY_PATH environment variable at run time for perl to find the library. On Windows, you have to set your PATH environment variable. 4. Callbacks ------------------------------ These Perl SAX callbacks are supported and tested: start_document() end_document() start_element() end_element() characters() processing_instruction() start_prefix_mapping() end_prefix_mapping() set_document_locator() fatal_error() comment() start_dtd() end_dtd() start_cdata() end_cdata() element_decl attribute_decl notation_decl() unparsed_entity_decl() external_entity_decl() internal_entity_decl() start_entity() end_entity () resolve_entity() skipped_entity() These methods are never called by XML::SAX::ExpatXS: warning() error() ignorable_whitespace() This one is deprecated but it works with XML::SAX::ExpatXS: xml_decl() 5. Encoding ------------------------------ These charsets and encodings are supported: UTF-8 (1) UTF-16 (1) US-ASCII (1) ISO-8859-1 (1) ISO-8859-2 (2) ISO-8859-3 (2) ISO-8859-4 (2) ISO-8859-5 (2) ISO-8859-7 (2) ISO-8859-8 (2) ISO-8859-9 (2) WINDOWS-1250 (2) WINDOWS-1252 (2) BIG5 (2) EUC-KR (2) EUC-JP (2,3) Shift JIS. (2,3) (1) Expat built-in (2) external handler (3) see lib/XML/SAX/ExpatXS/Encodings/Japanese_Encodings.msg Other encodings can be added with XML::Encoding, see lib/XML/SAX/ExpatXS/Encodings/README for more info.