You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@xerces.apache.org by ja...@apache.org on 2005/12/03 17:41:27 UTC
svn commit: r351984 - /xerces/xerces-p/trunk/README
Author: jasons
Date: Sat Dec 3 08:41:19 2005
New Revision: 351984
URL: http://svn.apache.org/viewcvs?rev=351984&view=rev
Log:
updated
Modified:
xerces/xerces-p/trunk/README
Modified: xerces/xerces-p/trunk/README
URL: http://svn.apache.org/viewcvs/xerces/xerces-p/trunk/README?rev=351984&r1=351983&r2=351984&view=diff
==============================================================================
--- xerces/xerces-p/trunk/README (original)
+++ xerces/xerces-p/trunk/README Sat Dec 3 08:41:19 2005
@@ -11,35 +11,23 @@
-1) Current Release: XML::Xerces 2.5.0-0
+1) Current Release: XML::Xerces 2.6.0-0
========================
-XML::Xerces is the Perl API to the Apache project's Xerces XML parser. It
-is implemented using the Xerces C++ API, and it provides access to *most*
-of the C++ API from Perl.
-
-Because it is based on Xerces-C, XML::Xerces provides a validating XML
-parser that makes it easy to give your application the ability to read and
-write XML data. Classes are provided for parsing, generating, manipulating,
-and validating XML documents. XML::Xerces is faithful to the XML 1.0
-recommendation and associated standards (DOM levels 1,2, and 3, SAX 1 and
-2, Namespaces, and W3C XML Schema). The parser provides high performance,
-modularity, and scalability, and provides full support for Unicode.
-
-XML::Xerces implements the vast majority of the Xerces-C API (if you notice
-any discrepancies please mail the list <URL:
-mailto:xerces-p-dev@xml.apache.org> ). The exception is some functions in
-the C++ API which either have better Perl counterparts (such as file I/O)
-or which manipulate internal C++ information that has no role in the Perl
-module.
-
-The majority of the API is created automatically using Simplified Wrapper
-Interface Generator (SWIG) <URL: http://www.swig.org/> . 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 Special Perl
-API Features section).
+XML::Xerces is the Perl API to the Apache project's Xerces XML parser. It is implemented using the Xerces C++ API, and it provides access to *most* of the C++ API from Perl.
-2) Available Platforms
+Because it is based on Xerces-C, XML::Xerces provides a validating XML parser that makes it easy to give your application the ability to read and write XML data. Classes are provided for parsing, generating, manipulating, and validating XML documents. XML::Xerces is faithful to the XML 1.0 recommendation and associated standards (DOM levels 1, 2, and 3, SAX 1 and 2, Namespaces, and W3C XML Schema). The parser provides high performance, modularity, and scalability, and provides full support for Unicode.
+
+XML::Xerces implements the vast majority of the Xerces-C API (if you notice any discrepancies please mail the list <URL: mailto:p-dev@xerces.apache.org> ). The exception is some functions in the C++ API which either have better Perl counterparts (such as file I/O) or which manipulate internal C++ information that has no role in the Perl module.
+
+The majority of the API is created automatically using Simplified Wrapper Interface Generator (SWIG) <URL: http://www.swig.org/> . 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 Special Perl API Features section).
+
+2) Support
+========================
+
+The online users mailing list is the place for any questions. It is at: p-dev@xerces.apache.org
+
+3) Available Platforms
========================
The code has been tested on the following platforms:
@@ -53,124 +41,93 @@
* AIX
* Tru64
-3) Build Requirements
+4) Build Requirements
========================
- 3.1) ANSI C++ compiler
+ 4.1) ANSI C++ compiler
------------------------
- Builds are known to work with the GNU C compiler, and other platform
- specific compilers (such as VC++ on Windows and Forte on Solaris).
- Contributions in this area are always welcome :-).
+Builds are known to work with the GNU C compiler, and other platform specific compilers (such as VC++ on Windows and Forte on Solaris). Contributions in this area are always welcome :-).
- 3.2) Perl5
+ 4.2) Perl5
------------------------
#### NOTE: ####
- Required version: 5.6.0
+Required version: 5.6.0
###############
- XML::Xerces now supports Unicode. Since Unicode support wasn't added to
- Perl until 5.6.0, you will need to upgrade in order to use this and
- future versions of XML::Xerces. Upgrading to at least to the latest
- stable release, 5.6.1, is recommended.
-
- If you plan on using Unicode, I *strongly* recommend upgrading to
- Perl-5.8.x, the latest stable version. There have been significant
- improvements to Perl's Unicode support.
+XML::Xerces now supports Unicode. Since Unicode support wasn't added to Perl until 5.6.0, you will need to upgrade in order to use this and future versions of XML::Xerces. Upgrading to at least to the latest stable release, 5.6.1, is recommended.
- 3.3) The Apache Xerces C++ XML Parser
+If you plan on using Unicode, I *strongly* recommend upgrading to Perl-5.8.x, the latest stable version. There have been significant improvements to Perl's Unicode support.
+
+ 4.3) The Apache Xerces C++ XML Parser
------------------------
#### NOTE: ####
- Required version: 2.5.0
+Required version: 2.6.0
###############
- (which can be downloaded from the apache archive <URL:
- http://www.apache.org/dist/xml/xerces-c/> ) You'll need both the
- library and header files, and to set up any environment variables that
- will direct the XML::Xerces build to the directories where these
- reside.
+(which can be downloaded from the apache archive <URL: http://www.apache.org/dist/xml/xerces-c/> ) You'll need both the library and header files, and to set up any environment variables that will direct the XML::Xerces build to the directories where these reside.
-4) Prepare for the build
+5) Prepare for the build
========================
- 4.1) Download XML::Xerces
+ 5.1) Download XML::Xerces
------------------------
- Download the release and it's digital signature, from the apache
- Xerces-C archive <URL: http://xml.apache.org/dist/xerces-p/stable> .
+Download the release and it's digital signature, from the apache Xerces-C archive <URL: http://xml.apache.org/dist/xerces-p/stable> .
- 4.2) Verify the archive
+ 5.2) Verify the archive
------------------------
- Optionally verify the release using the supplied digital signature (see
- the apache Xerces-Perl archive <URL:
- http://xml.apache.org/xerces-p/download.html> for details)
+Optionally verify the release using the supplied digital signature (see the apache Xerces-Perl archive <URL: http://xml.apache.org/xerces-p/download.html> for details)
- 4.3) Unpack the archive
+ 5.3) Unpack the archive
------------------------
- Unpack the archive in a directory of your choice. Example (for UNIX):
+Unpack the archive in a directory of your choice. Example (for UNIX):
- * tar zxvf XML-Xerces-2.5.0-0.tar.gz
- * cd XML-Xerces-2.5.0-0
+ * tar zxvf XML-Xerces-2.6.0-0.tar.gz
+ * cd XML-Xerces-2.6.0-0
- 4.4) Getting Xerces-C
+ 5.4) Getting Xerces-C
------------------------
- 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 directions for
- building XML::Xerces.
+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 directions for building XML::Xerces.
- Otherwise, you must download Xerces-C from www.apache.org. If there is
- a binary available for your architecture, you may use it, otherwise you
- must build it from source. If you wish to make Xerces-C available to
- other applications, you may install it however it is not necessary to
- do so in order to build XML::Xerces. To build XML::Xerces from an
- uninstalled Xerces-C set the XERCESCROOT environment variable the
- top-level directory of the source directory (i.e. the same value it
- needs to be to build Xerces-C):
+Otherwise, you must download Xerces-C from www.apache.org. If there is a binary available for your architecture, you may use it, otherwise you must build it from source. If you wish to make Xerces-C available to other applications, you may install it however it is not necessary to do so in order to build XML::Xerces. To build XML::Xerces from an uninstalled Xerces-C set the XERCESCROOT environment variable the top-level directory of the source directory (i.e. the same value it needs to be to build Xerces-C):
- export XERCESCROOT=/home/jasons/xerces-2.5.0/
+ export XERCESCROOT=/home/jasons/xerces-&XERCES_C_VERSION;/
- If you choose to install Xerces-C on your system, you need to set the
- XERCES_INCLUDE and XERCES_LIB environment variables:
+OPTIONAL: If you choose to install Xerces-C on your system, you need to set the XERCES_INCLUDE and XERCES_LIB environment variables:
export XERCES_INCLUDE=/usr/include/xerces
export XERCES_LIB=/usr/lib
-5) Build XML::Xerces
+6) Build XML::Xerces
========================
- A) Go to the XML-Xerces-2.5.0-0 directory.
- B) Build XML::Xerces as you would any perl package that you might get from
- CPAN:
+ A) Go to the XML-Xerces-2.6.0-0 directory.
+ B) Build XML::Xerces as you would any perl package that you might get from CPAN:
* perl Makefile.PL
* make
* make test
* make install
-6) Using XML::Xerces
+7) Using XML::Xerces
========================
-XML::Xerces 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 online <URL: http://xml.apache.org/xerces-c/apiDocs/index.html> .
+XML::Xerces 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 online <URL: http://xml.apache.org/xerces-c/apiDocs/index.html> .
-For more information, see the examples in the samples/ directory. and the
-test scripts located in the t/ directory.
+For more information, see the examples in the samples/ directory. and the test scripts located in the t/ directory.
-7) Special Perl API Features
+8) Special Perl API Features
========================
-Even though XML::Xerces 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:
+Even though XML::Xerces 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:
* String I/O (Perl strings versus XMLch arrays)
* List I/O (Perl lists versus DOM_NodeList's)
@@ -181,23 +138,15 @@
* handling C++ exceptions
* XML::Xerces::XMLUni unicode constants
- 7.1) String I/O
+ 8.1) String I/O
------------------------
- Any functions in the C++ API that return XMLCh arrays will return plain
- vanilla perl-strings in XML::Xerces. This obviates calls to transcode
- (in fact, it makes them entirely invalid).
+Any functions in the C++ API that return XMLCh arrays will return plain vanilla perl-strings in XML::Xerces. This obviates calls to transcode (in fact, it makes them entirely invalid).
- 7.2) List I/O
+ 8.2) List I/O
------------------------
- Any function that in the C++ API returns a DOMNodeList (e.g.
- getChildNodes() and getElementsByTagName() 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
- XML::Xerces::DOMNodeList, just like in C++ API. However, in a list
- context they will return a Perl list of XML::Xerces::DOM_Node
- references. For example:
+Any function that in the C++ API returns a DOMNodeList (e.g. getChildNodes() and getElementsByTagName() 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 XML::Xerces::DOMNodeList, just like in C++ API. However, in a list context they will return a Perl list of XML::Xerces::DOM_Node references. For example:
# returns a reference to a XML::Xerces::DOMNodeList
@@ -206,15 +155,10 @@
# returns a list of XML::Xerces::DOMNode's
my @node_list = $doc->getElementsByTagName('foo');
- 7.3) Hash I/O
+ 8.3) Hash I/O
------------------------
- Any function that in the C++ API returns a DOMNamedNodeMap
- (getEntities() and getAttributes() 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
- XML::Xerces::DOMNamedNodeMap, just like in C++ API. However, in a list
- context they will return a Perl hash. For example:
+Any function that in the C++ API returns a DOMNamedNodeMap (getEntities() and getAttributes() 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 XML::Xerces::DOMNamedNodeMap, just like in C++ API. However, in a list context they will return a Perl hash. For example:
# returns a reference to a XML::Xerces::DOMNamedNodeMap
@@ -223,14 +167,10 @@
# returns a hash of the attributes
my %attrs = $element_node->getAttributes();
- 7.4) Combined List/Hash classes (XMLAttDefList)
+ 8.4) Combined List/Hash classes (XMLAttDefList)
------------------------
- Any function that in the C++ API returns a XMLAttDefList
- (getAttDefList() for SchemaElementDecl and DTDElementDecl), will always
- return an instance of XML::Xerces::XMLAttDefList. However, there are
- two Perl specific API methods that can be invoked on the object:
- to_list() and to_hash().
+Any function that in the C++ API returns a XMLAttDefList (getAttDefList() for SchemaElementDecl and DTDElementDecl), will always return an instance of XML::Xerces::XMLAttDefList. However, there are two Perl specific API methods that can be invoked on the object: to_list() and to_hash().
# get the XML::Xerces::XMLAttDefList.
@@ -244,30 +184,23 @@
# values are the XML::Xerces::XMLAttDef instances.
my %attrs = $attr_list->to_hash();
- 7.5) Serialize API
+ 8.5) Serialize API
------------------------
- The DOMWriter class is used for serializing DOM hierarchies. See
- t/DOMWriter.t or samples/DOMPrint.pl for details.
+The DOMWriter class is used for serializing DOM hierarchies. See t/DOMWriter.t or samples/DOMPrint.pl for details.
- For less complex usage, just use the serialize() method defined for all
- DOMNode subclasses.
+For less complex usage, just use the serialize() method defined for all DOMNode subclasses.
- 7.6) Implementing {Document,Content,Error}Handlers from Perl
+ 8.6) Implementing {Document,Content,Error}Handlers from Perl
------------------------
- Thanks to suggestions from Duncan Cameron, XML::Xerces 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:
+Thanks to suggestions from Duncan Cameron, XML::Xerces 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:
* PerlErrorHandler (SAX 1/2 and DOM 1)
* PerlDocumentHandler (SAX 1)
* PerlContentHandler (SAX 2)
- 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:
+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:
package MyErrorHandler;
@@ -278,93 +211,63 @@
my $dom = new XML::Xerces::DOMParser;
$dom->setErrorHandler(MyErrorHandler->new());
- 7.7) Handling exceptions ({XML,DOM,SAX}Exception's)
+ 8.7) Handling exceptions ({XML,DOM,SAX}Exception's)
------------------------
- Some errors occur outside parsing and are not caught by the parser's
- ErrorHandler. XML::Xerces provides a way for catching these errors
- using the PerlExceptionHandler class. Usually the following code is
- enough for catching exceptions:
+Some errors occur outside parsing and are not caught by the parser's ErrorHandler. XML::Xerces provides a way for catching these errors using the PerlExceptionHandler class. Usually the following code is enough for catching exceptions:
eval{$parser->parser($my_file)};
XML::Xerces::error($@) if $@;
- Wrap any code that might throw an exception inside an eval{...} and
- call XML::Xerces::error() passing $@, if $@ is set.
+Wrap any code that might throw an exception inside an eval{...} and call XML::Xerces::error() passing $@, if $@ is set.
+
+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.
- 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.
-
- 7.8) XML::Xerces::XMLUni unicode constants
- ------------------------
-
- XML::Xerces uses many constant values for setting of features, and
- properties, such as for XML::Xerces::SAX2XMLReader::setFeature(). You
- can hard code the strings or integers into your programs but this will
- make them vulnerable to an API change. Instead, use the constants
- defined in the XML::Xerces::XMLUni class. If the API changes, the
- constants will be updated to reflect that change. See the file
- docs/UMLUni.txt for a complete listing of the constant names and their
- values.
+ 8.8) XML::Xerces::XMLUni unicode constants
+ ------------------------
+
+XML::Xerces uses many constant values for setting of features, and properties, such as for XML::Xerces::SAX2XMLReader::setFeature(). You can hard code the strings or integers into your programs but this will make them vulnerable to an API change. Instead, use the constants defined in the XML::Xerces::XMLUni class. If the API changes, the constants will be updated to reflect that change. See the file docs/UMLUni.txt for a complete listing of the constant names and their values.
-8) Sample Code
+9) Sample Code
========================
XML::Xerces comes with a number of sample applications:
- * SAXCount.pl: Uses the SAX interface to output a count of the number of
- elements in an XML document
- * SAX2Count.pl: Uses the SAX2 interface to output a count of the number of
- elements in an XML document
- * DOMCount.pl: Uses the DOM interface to output a count of the number of
- elements in an XML document
- * DOMPrint.pl: Uses the DOM interface to output a pretty-printed version of
- an XML file to STDOUT
- * DOMCreate.pl: Creates a simple XML document using the DOM interface and
- writes it to STDOUT
- * DOM2hash.pl: Uses the DOM interface to convert the file to a simple hash of
- lists representation
- * EnumVal.pl: Parses and input XML document and outputs the DTD information
- to STDOUT
- * SEnumVal.pl: Parses and input XML document and outputs the XML Schema
- information to STDOUT
+ * SAXCount.pl: Uses the SAX interface to output a count of the number of elements in an XML document
+ * SAX2Count.pl: Uses the SAX2 interface to output a count of the number of elements in an XML document
+ * DOMCount.pl: Uses the DOM interface to output a count of the number of elements in an XML document
+ * DOMPrint.pl: Uses the DOM interface to output a pretty-printed version of an XML file to STDOUT
+ * DOMCreate.pl: Creates a simple XML document using the DOM interface and writes it to STDOUT
+ * DOM2hash.pl: Uses the DOM interface to convert the file to a simple hash of lists representation
+ * EnumVal.pl: Parses and input XML document and outputs the DTD information to STDOUT
+ * SEnumVal.pl: Parses and input XML document and outputs the XML Schema information to STDOUT
-9) Development Tools
+10) Development Tools
========================
#### NOTE: ####
- These are only for internal XML::Xerces development. If your
- intention is solely to use XML::Xerces to write XML applications in
- Perl, you will *NOT* need these tools.
+These are only for internal XML::Xerces development. If your intention is solely to use XML::Xerces to write XML applications in Perl, you will *NOT* need these tools.
###############
- 9.1) SWIG
+ 10.1) SWIG
------------------------
- Simplified Wrapper Interface Generator (SWIG) <URL:
- http://www.swig.org/> 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 the SWIG home page <URL: http://www.swig.org/>
- and then build it for your platform.
-
- You will only need this if the include Xerces.C and XML::Xerces files
- do not work for your perl distribution. The pre-generated files have
- been created by SWIG 1.3 and work under Perl-5.6 or later.
-
- This port will only work with SWIG 1.3.20 (which is currently only
- available via CVS).
-
- If your planning to use SWIG, you can set the environment variable SWIG
- to the full path to the SWIG executable before running perl
- Makefile.pl. For example:
+Simplified Wrapper Interface Generator (SWIG) <URL: http://www.swig.org/> 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 the SWIG home page <URL: http://www.swig.org/> and then build it for your platform.
+
+You will only need this if the include Xerces.C and XML::Xerces files do not work for your perl distribution. The pre-generated files have been created by SWIG 1.3 and work under Perl-5.6 or later.
+
+This port will only work with SWIG 1.3.20 (which is currently only available via CVS).
+
+If your planning to use SWIG, you can set the environment variable SWIG to the full path to the SWIG executable before running perl Makefile.pl. For example:
export SWIG=/usr/bin/swig
- This is only necessary if it isn't in your path or you have more than
- one version installed.
+This is only necessary if it isn't in your path or you have more than one version installed.
+
+11) Acknowledgements
+========================
+
+The Xerces development team would like to provide special acknowledgment to Cluster Technology Limited <URL: http://clustertech.com/> for providing financial support for the XML-Xerces-2.6 release and for invaluable testing to help eliminate the major memory leaks that existed prior to the 2.6 release.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@xerces.apache.org
For additional commands, e-mail: commits-help@xerces.apache.org