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: [EMAIL PROTECTED] For additional commands, e-mail: [EMAIL PROTECTED]
