You are viewing a plain text version of this content. The canonical link for it is here.
Posted to general-cvs@xml.apache.org by ja...@apache.org on 2001/03/27 02:38:31 UTC
cvs commit: xml-site/sources/xerces-p readme.xml
jasons 01/03/26 16:38:31
Modified: sources/xerces-p readme.xml
Log:
Updated for Xerces.pm 1.3
Revision Changes Path
1.3 +126 -9 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- readme.xml 1999/12/01 23:37:23 1.2
+++ readme.xml 2001/03/27 00:38:31 1.3
@@ -2,15 +2,132 @@
<!DOCTYPE s1 SYSTEM "sbk:/style/dtd/document.dtd">
<s1 title="Xerces Perl">
- <s2 title="Xerces-P version 1.0">
- <p>
- A Perl wrapper is provided for the C++ version of Xerces, which allows
- access to a fully validating DOM XML parser from Perl. It also
- provides for full access to Unicode strings, since Unicode is a key
- part of the XML standard.
+ <p> The Xerces Perl project provides a Perl module, Xerces.pm,
+ 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 all of the C++ 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 fullly-featured release of Xerces.pm. It
+ provides access to <em>all</em> functionality in the Xerces-C 1.3
+ API.
</p>
- <p>
- Additional documentation to be provided soon. Watch this space.
+ </s2>
+ <s2 title="Special Perl API Features">
+ <p> Special handling has been provided for certain functions:
+ <anchor name="perl-api"/>
</p>
+ <ul>
+ <li> <link anchor="string">String I/O</link> (Perl strings versus DOMString's, XMLch *'s)</li>
+ <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>
+ </ul>
+
+ <s3 title="String I/O">
+ <p><anchor name="string"/>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>
+
+ <source><![CDATA[
+ document.createElement( new DOMString("foo") );
+ ]]></source>
+
+ in Xerces.pm, you can use either of:
+
+ <source><![CDATA[
+ $document->createElement( XML::Xerces::DOMString->new('foo') );
+ ]]></source>
+
+ or the less cumbersome:
+
+ <source><![CDATA[
+ $document->createElement('foo');
+ ]]></source>
+
+ <p> As well, any functions in the C++ API that return
+ string-like values, i.e. like <code>DOMString</code>'s and
+ <code>XMLCh</code> arrays, return plain vanilla perl-strings in
+ Xerces.pm. This obviates calls to <code>transcode</code> (in
+ fact, it makes them entirely invalid).
+ </p>
+ </s3>
+ <s3 title="List I/O">
+ <p><anchor name="list"/>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
+ different types if they are called in a list context or a scalar
+ context. In a scalar context, these functions return a reference
+ to a <code>XML::Xerces::DOM_NodeList</code>, just like in C++
+ API. However, in a list context they will return a Perl list of
+ <code>XML::Xerces::DOM_Node</code> references. For example:
+ </p>
+ <source><![CDATA[
+ # returns a reference to a XML::Xerces::DOM_NodeList
+ my $node_list_ref = $doc->getElementsByTagName('foo');
+
+ # returns a list of XML::Xerces::DOM_Node's
+ my @node_list = $doc->getElementsByTagName('foo');
+ ]]></source>
+
+ </s3>
+ <s3 title="Hash I/O">
+ <p><anchor name="hash"/> 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
+ list context or a scalar context. In a scalar context, these
+ functions return a reference to a
+ <code>XML::Xerces::DOM_NamedNodeMap</code>, just like in C++
+ API. However, in a list context they will return a Perl
+ hash. For example:
+ </p>
+
+ <source><![CDATA[
+ # returns a reference to a XML::Xerces::DOM_NamedNodeMap
+ my $attr_map_ref = $element_node->getAttributes();
+
+ # returns a hash of the attributes
+ my %attrs = $element_node->getAttributes();
+ ]]></source>
+ </s3>
+ <s3 title="Serialize API">
+ <p><anchor name="serialize"/> 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>
+ </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="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="domcreate">DOMCreate.pl</link>: Creates a simple XML
+ document using the DOM interface and writes it to STDOUT</li>
+ </ul>
</s2>
-</s1>
\ No newline at end of file
+</s1>
---------------------------------------------------------------------
To unsubscribe, e-mail: general-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: general-cvs-help@xml.apache.org