jasons 01/07/08 22:15:36
Modified: sources/xerces-p readme.xml
Log:
* readme.xml (Repository):
Now matches README from distribution
Revision Changes Path
1.5 +248 -37 xml-site/sources/xerces-p/readme.xml
Index: readme.xml
===================================================================
RCS file: /home/cvs/xml-site/sources/xerces-p/readme.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- readme.xml 2001/03/27 05:48:38 1.4
+++ readme.xml 2001/07/09 05:15:36 1.5
@@ -1,39 +1,195 @@
<?xml version="1.0" standalone="no"?>
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
-<s1 title="Xerces Perl">
- <p> The Xerces Perl project has created a Perl module,
- <em>Xerces.pm</em>, as the Perl API to the Apache project's Xerces
- XML parser. It is implemented using the Xerces C++ API, and it
- provides access to all of the C++ API from Perl.
- </p>
-
- <p> Because it is based on Xerces-C, Xerces.pm provides a validating
- XML parser that makes it easy to give your application the ability
- to read and write XML data. A shared library is provided for
- parsing, generating, manipulating, and validating XML
- documents. Xerces.pm is faithful to the XML 1.0 recommendation and
- associated standards ( DOM 1.0, DOM 2.0. SAX 1.0, SAX 2.0,
- Namespaces), The parser provides high performance, modularity, and
- scalability. Source code, samples and API documentation are provided
- with the parser.
- </p>
-
- <p> The majority of the API is created automatically using <jump
- href="http://www.swig.org/";>Simplified Wrapper Interface Generator
- (SWIG)</jump>. However, care has been taken to make most method
- invocations natural to perl programmers, so a number of rough C++
- edges have been smoothed over (See the <link
- anchor='perl-api'>Special Perl API Features</link> section).
- </p>
- <s2 title="Xerces.pm version 1.3">
- <p> This is the first fully-featured release of Xerces.pm. It
- provides access to <em>all</em> functionality in the Xerces-C 1.3
- API.
+<s1 title="Xerces.pm: The Perl API to the Apache Xerces XML parser">
+ <s2 title="Xerces.pm 1.5.0">
+ <p> This module implements the Perl API to the Apache project's
+ Xerces XML parser. It is implemented using the Xerces C++ API, and
+ it provides access to <em>most</em> of the C++ API from Perl.
</p>
+
+ <p> Because it is based on Xerces-C, Xerces.pm provides a validating
+ XML parser that makes it easy to give your application the
+ ability to read and write XML data. A shared library is provided
+ for parsing, generating, manipulating, and validating XML
+ documents. Xerces.pm is faithful to the XML 1.0 recommendation
+ and associated standards (DOM 1.0, DOM 2.0. SAX 1.0, SAX 2.0,
+ Namespaces, and Schema), The parser provides high performance,
+ modularity, and scalability.
+ </p>
+
+ <p>Xerces.pm implements the vast majority of the Xerces-C API (if you
+ notice any discrepancies please mail the <jump
+ href="mailto:[email protected]";>list</jump>). The
+ exception of this is functions in the C++ API which have been
+ overloaded to accept different arguments, currently have only a
+ single version in the Perl API. This is a simple fix, but will
+ take time.
+ </p>
+
+ <p> The majority of the API is created automatically using <jump
+ href="http://www.swig.org/";>Simplified Wrapper Interface Generator
+ (SWIG)</jump>. However, care has been taken to make most method
+ invocations natural to perl programmers, so a number of rough C++
+ edges have been smoothed over (See the <link
+ anchor='perl-api'>Special Perl API Features</link> section).
+ </p>
+ </s2>
+ <s2 title="Available Platforms">
+ <p> The code has been tested on the following Unix platforms: </p>
+ <ul>
+ <li>Linux</li>
+ <ul>
+ <li>PPC-debian: works jason</li>
+ <li>x86-debian: works harmon</li>
+ <li>x86-redhat6.2: works jason</li>
+ <li>x86-redhat7: works jason (recompile Xerces-C and
+ Perl-5.6.1 from source)</li>
+ </ul>
+ <li>BSD</li>
+ <ul>
+ <li>NetBSD (egcs-2.91.66, works: Emanuel Dreyfus
+ <[EMAIL PROTECTED]>)</li>
+ </ul>
+ <li>Solaris </li>
+ <ul>
+ <li>Solaris 8: works cc and gcc (recompile perl and Xerces-C from
source)</li>
+ <li>Solaris 5.6: works gcc</li>
+ </ul>
+ </ul>
+ <p>Windows is currently not supported. However, minimal changes would be
+ necessary to enable functionality under Windows (modification of
+ some Unix 'make' specific code in Makefile.PL).
+ </p>
+ </s2>
+ <s2 title="Build Requirements">
+ <ol>
+ <li>An ANSI C++ compiler. Builds are known to work with the GNU
+ compiler. Ports to other compilers such as MSVC++ (the Microsoft
+ Visual C++ compiler and development environment) are in the works.
+ Contributions in this area are always welcome :-).
+ </li>
+ <li>Perl5 (Xerces.pm has been tested with perl 5.005 and 5.6).
+ Currently only tested on XML documents that are encoded in plain
+ old ASCII.
+ </li>
+ <li>The Apache Xerces C++ XML Parser version 1.5 (which can be
+ downloaded from: <jump
+
href="http://xml.apache.org/dist/xerces-c/stable/";>http://xml.apache.org/dist/xerces-c/stable/</jump>
+ <br/><br/>
+ You'll need both the library and header files, and to set up any
+ environment variables that will direct the Xerces.pm build to the
+ directories where these reside.
+ </li>
+ </ol>
+ </s2>
+ <s2 title="Optional Components">
+ <p><jump href="http://www.swig.org/";> Simplified Wrapper Interface
+ Generator (SWIG)</jump> is an open source tool by David Beazley of
+ the University of Chicago for automatically generating Perl
+ wrappers for C and C++ libraries (i.e. *.a or *.so for UNIX, *.dll
+ for Windoes). You can get the source from <jump
+ href="http://www.swig.org/";>www.swig.org</jump> and then build it
+ for your platform.
+ </p>
+ <p>You will only need this if the include Xerces.C and Xerces.pm
+ files do not work for your perl distribution. The pre-generated
+ files have been created by SWIG 1.3 and work under perl-5.005
+ and perl-5.6.
+ </p>
+ <p>
+ This port is know to work with versions 1.1p5 and 1.3a5 of SWIG.
+ </p>
+ <p>
+ If your planning to use SWIG, you can set the environment variable
+ SWIG to the full path to the SWIG executable before running <code>perl
+ Makefile.pl</code>. For example:</p>
+ <ul>
+ <li><code>export SWIG=/usr/bin/swig</code></li>
+ </ul>
+ <p>
+ This is only necessary if it isn't in your path or you have more
+ than one version installed.
+ </p>
+ </s2>
+ <s2 title="Prepare for the build">
+ <ol>
+ <li>Unpack the archive in a directory of your choice. Example (for
+ UNIX):</li>
+ <ul>
+ <li><code>cd <DIRECTORY OF YOUR CHOICE></code></li>
+ <li><code>tar xvf <DIRECTORY Xerces-1.5.x.tar.gz IS
+ LOCATED>/Xerces-1.5.x.tar.gz</code></li>
+ </ul>
+ <li>Go to the Xerces-1.5.x directory:</li>
+ <ul>
+ <li><code>cd Xerces-1.5.x</code></li>
+ </ul>
+ <li>Examine the Perl script "Makefile.PL". You may need to change
+ some locations of libraries and include directories. If you
+ attempt to build on a platform other than UNIX, you will probably
+ have to change more.
+ <br/><br/>
+ Also, you may want to edit the path to the swig executable
+ ($SWIG), if you're planning on regenerating Xerces.C and
+ Xerces.pm
+ </li>
+ <li>If the Xerces-C library and header files are installed on your
+ system directly, e.g. via an rpm or deb package, proceed to the
+ build.
+ <br/><br/>
+ Otherwise, you must download Xerces from xml.apache.org and build
+ it. To build Xerces.pm in this case, make sure the value of your
+ XERCESCROOT environment variable is the top-level directory of
+ your xerces distribution (i.e. the same value it needs to be to
+ build XERCES).
+ <br/><br/>
+ If you have built Xerces-C yourself and want to work directly from
+ the build directory, then you should only need to set the
+ XERCESCROOT environment variable.
+ If you have installed xerces on your system you should only need
+ to set the XERCES_INCLUDE and XERCES_LIB environment
+ variables. For example:
+ </li>
+ <ul>
+ <li><code>export
+ XERCES_INCLUDE=/usr/include/xerces</code></li>
+ <li><code>export XERCES_LIB=/usr/lib</code></li>
+ </ul>
+ </ol>
</s2>
+ <s2 title="Build Xerces.pm">
+ <ol>
+ <li>Go to the Xerces-1.5.x directory.</li>
+ <li>Build Xerces.pm as you would any perl package that you might get
+ from CPAN: </li>
+ <ul>
+ <li><code>perl Makefile.PL</code></li>
+ <li><code>make</code></li>
+ <li><code>make test</code></li>
+ <li><code>make install</code></li>
+ </ul>
+ </ol>
+ </s2>
+ <s2 title="Using Xerces.pm">
+ <p>
+ Xerces.pm implements the vast majority of the Xerces-C API (if
+ you notice any discrepancies please mail the
+ list). Documentation for this API are sadly not available in POD
+ format, but the Xerces-C html documentation is available at:
+ <jump href="http://xml.apache.org/xerces-c/apiDocs/index.html";>
+ http://xml.apache.org/xerces-c/apiDocs/index.html </jump></p>
+ <p>
+ For more information, see the sample scripts: DOMCount.pl,
+ DOMCreate.pl, and DOMPrint.pl in the samples/ directory, or the test
+ scripts located in the t/ directory (especially the TestUtils.pm
+ module).
+ </p>
+ </s2>
<s2 title="Special Perl API Features">
- <p> Special handling has been provided for certain functions:
+ <p> Even though Xerces.pm is based on the C++ API, it has been modified
in
+ a few ways to make it more accessible to typical Perl usage,
+ primarily in the handling:
<anchor name="perl-api"/>
</p>
<ul>
@@ -41,10 +197,13 @@
<li> <link anchor="list">List I/O</link> (Perl lists versus
DOM_NodeList's)</li>
<li> <link anchor="hash">Hash I/O</link> (Perl hashes versus
DOM_NamedNodeMap's)</li>
<li> <link anchor="serialize">Serialize API</link></li>
+ <li> <link anchor="handlers">Implementing Perl handlers for C++
+ even callbacks</link></li>
+ <li> <link anchor="exceptions">handling C++ exceptions</link></li>
</ul>
-
+ <p><anchor name="string"/></p>
<s3 title="String I/O">
- <p><anchor name="string"/>Note that the creation of
+ <p>Note that the creation of
<code>DOMString</code>'s as arguments to to functions is
optional. That is, where in C++ you'd have to use:</p>
@@ -71,8 +230,9 @@
fact, it makes them entirely invalid).
</p>
</s3>
+ <p><anchor name="list"/></p>
<s3 title="List I/O">
- <p><anchor name="list"/>Any function that in the C++ API returns
+ <p>Any function that in the C++ API returns
a <code>DOM_NodeList</code> (<em>e.g.</em>
<code>getChildNodes()</code> and
<code>getElementsByTagName()</code> for example) will return
@@ -91,8 +251,9 @@
]]></source>
</s3>
+ <p><anchor name="hash"/></p>
<s3 title="Hash I/O">
- <p><anchor name="hash"/> Any function that in the C++ API
+ <p> Any function that in the C++ API
returns a <code>DOM_NamedNodeMap</code>
(<code>getEntities()</code> and <code>getAttributes()</code> for
example) will return different types if they are called in a
@@ -111,21 +272,71 @@
my %attrs = $element_node->getAttributes();
]]></source>
</s3>
+ <p><anchor name="serialize"/></p>
<s3 title="Serialize API">
- <p><anchor name="serialize"/> The XML::Xerces::DOMParse module
implements a generic
+ <p>The XML::Xerces::DOMParse module implements a generic
serializer API for DOM Trees. See the script <link
idref="domprint"> DOMPrint.pl</link> for an example of how to
use the API.
</p>
+ <p>For less complex usage, just use the serialize() method defined for
+ all DOM_Node subclasses.
+ </p>
+ </s3>
+ <p><anchor name="handlers"/></p>
+ <s3 title="Implementing {Document,Content,Error}Handlers from Perl
+ ">
+ <p>Thanks to suggestions from Duncan Cameron, Xerces.pm now has a
handler
+ API that matches the currently used semantics of other Perl
+ XML API's. There are three classes available for application
+ writers:</p>
+ <ul>
+ <li>PerlErrorHandler (SAX 1/2 and DOM 1)</li>
+ <li>PerlDocumentHandler (SAX 1)</li>
+ <li>PerlContentHandler (SAX 2)</li>
+ </ul>
+ <p>Using these classes is as simple as creating a perl subclass of the
+ needed class, and redefining any needed methods. For example,
+ to override the default fatal_error() method of the
+ PerlErrorHandler class we can include this piece of code
+ within our application:</p>
+ <source><![CDATA[
+
+ package MyErrorHandler;
+ @ISA = qw(XML::Xerces::PerlErrorHandler);
+ sub fatal_error {die "Oops, I got an error\n";}
+
+ package main;
+ my $dom = new XML::Xerces::DOMParser;
+ $dom->setErrorHandler(MyErrorHandler->new());
+
+]]></source>
+ </s3>
+ <p><anchor name="exceptions"/></p>
+ <s3 title="Handling exceptions ({XML,DOM,SAX}Exception's)">
+ <p>Some errors occur outside parsing and are not caught by the parser's
+ ErrorHandler. Xerces.pm provides a way for catching these errors using
+ the PerlExceptionHandler class.
+ </p>
+ <p>
+ There are a default methods that prints out an error message and calls
+ die(), but if more is needed, see the files t/XMLException.t,
+ t/SAXException.t, and t/DOMException.t for details on how to roll your
+ own handler.
+ </p>
</s3>
</s2>
<s2 title="Sample Code">
<p> Xerces.pm comes with three sample applications:</p>
<ul>
- <li> <link idref="domprint">DOMPrint.pl</link>: Uses the DOM
- interface to output a pretty-printed version of an XML file to STDOUT
</li>
+ <li> <link idref="saxcount">SAXCount.pl</link>: Uses the SAX
+ interface to output a count of the number of elements in an XML
document</li>
+ <li> <link idref="sax2count">SAX2Count.pl</link>: Uses the SAX2
+ interface to output a count of the number of elements in an XML
document</li>
<li> <link idref="domcount">DOMCount.pl</link>: Uses the DOM
interface to output a count of the number of elements in an XML
document</li>
+ <li> <link idref="domprint">DOMPrint.pl</link>: Uses the DOM
+ interface to output a pretty-printed version of an XML file to STDOUT
</li>
<li> <link idref="domcreate">DOMCreate.pl</link>: Creates a simple XML
document using the DOM interface and writes it to STDOUT</li>
</ul>
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
