[prev in list] [next in list] [prev in thread] [next in thread]
List: xerces-cvs
Subject: cvs commit: xml-xerces/perl README
From: jasons () apache ! org
Date: 2001-03-26 21:39:30
[Download RAW message or body]
jasons 01/03/26 13:39:30
Modified: perl README
Log:
* README (Repository):
Added a DESCRIPTION
Revision Changes Path
1.6 +143 -114 xml-xerces/perl/README
Index: README
===================================================================
RCS file: /home/cvs/xml-xerces/perl/README,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- README 2001/03/16 16:17:49 1.5
+++ README 2001/03/26 21:39:29 1.6
@@ -1,30 +1,59 @@
Xerces.pm: The Perl API to the Apache Xerces XML parser
- $Id: README,v 1.5 2001/03/16 16:17:49 jasons Exp $
+ $Id: README,v 1.6 2001/03/26 21:39:29 jasons Exp $
LEGAL HOOP JUMPING:
===================
This code is distributed under the terms of the Apache Software
License, Version 1.1. See the file LICENSE for details
+DESCRIPTION:
+============
+
+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 all of the C++ from Perl.
+
+From the Xerces-C project homepage:
+
+ "Xerces-C is a validating XML parser written in a portable subset
+ of C++. Xerces-C 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-C 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."
+
+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).
+
+AVAILABLE PLATFORMS:
+====================
+
+The code has currently only been tested under Linux. However, minimal
+changes would be necessary to enable functionality under Windows
+(modification of some Unix 'make' specific code in Makefile.PL).
BUILD REQUIREMENTS:
===================
+
+1. 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 :-).
+
+2. 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.
-1. 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 :-).
-
-2. 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.
-
-3. The Apache Xerces C++ XML Parser version 1.3 (which can be
- downloaded from:
- http://xml.apache.org/dist/xerces-c/stable/archives/Xerces-C_1_3_0/
+3. The Apache Xerces C++ XML Parser version 1.3 (which can be
+ downloaded from:
+ http://xml.apache.org/dist/xerces-c/stable/archives/Xerces-C_1_3_0/
+
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.
@@ -32,8 +61,8 @@
OPTIONAL COMPONENTS
===================
-1. SWIG - (Simplified Wrapper and Interface Generator) An open
- source tool by David Beazley of the University of Chicago for
+1. SWIG - (Simplified Wrapper and Interface Generator) 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 www.swig.org and then build it for your platform.
@@ -45,9 +74,9 @@
This port is know to work with versions 1.1p5 and 1.3a5 of SWIG.
- 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:
+ 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
@@ -57,34 +86,33 @@
PREPARE FOR THE BUILD:
======================
-1. Unpack the archive in a directory of your choice.
- Example (for UNIX):
+1. Unpack the archive in a directory of your choice. Example (for
+ UNIX):
cd <DIRECTORY OF YOUR CHOICE>
tar xvf <DIRECTORY Xerces-1.3.x.tar.gz IS LOCATED>/Xerces-1.3.x.tar.gz
-2. Go to the Xerces-1.3.x directory:
+2. Go to the Xerces-1.3.x directory:
- cd Xerces-1.3.x
+ cd Xerces-1.3.x
-3. 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.
+3. 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.
Also, you may want to edit the path to the swig executable
($SWIG), if you're planning on regenerating Xerces.C and Xerces.pm
-4. If the XERCES library and header files are installed
- on your system directly, e.g. via an rpm or deb package,
- proceed to the build.
-
- 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).
+4. If the XERCES library and header files are installed on your
+ system directly, e.g. via an rpm or deb package, proceed to the
+ build.
+
+ 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).
If you have installed xerces on your system you should only need
to set the XERCES_INCLUDE and XERCES_LIB environment
@@ -95,39 +123,39 @@
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.
+ XERCESCROOT environment variable.
BUILD Xerces.pm:
===============
-1. Go to the Xerces-1.3.x directory.
+1. Go to the Xerces-1.3.x directory.
-2. Build Xerces.pm as you would any perl package
- that you might get from CPAN:
+2. Build Xerces.pm as you would any perl package that you might get
+ from CPAN:
perl Makefile.PL
make
make test
make install
-3. Hopefully step 2 went smoothly. If not, let
- us know via the xerces-p-dev@xml.apache.org
- mailing list. If you're able to get it working
- yourself, please post any mods you made to this same
- mailing list.
-
-
USING Xerces.pm:
================
-Xerces.pm implements the entire XERCES API for DOM (not SAX).
-Docs for this API are available at
-http://xml.apache.org/xerces-c/apiDocs/index.html
+Xerces.pm implements the entire XERCES API for DOM (not SAX). Docs
+for this API are available at:
-Special Perl API Features
--------------------------
+ http://xml.apache.org/xerces-c/apiDocs/index.html
+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).
+
+
+Special Perl API Features:
+==========================
+
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:
@@ -136,70 +164,66 @@
* hashes (DOM_NamedNodeMap and perl hash)
* actual_cast() (for re-blessing DOM_Node subclasses)
* DOMParse.pm (for pretty printing a DOM tree)
-
- Handling of DOMString's and XMLCh's
- ----------------------------------
-
- Note that the creation of DOMStrings as arguments to
- to functions is optional. That is, where in C++ you'd have to use:
-
- document.createElement( new DOMString("foo") );
-
- in Xerces.pm, you can use either of:
-
- $document->createElement( new DOMString('foo') );
-
- or the less cumbersome:
-
- $document->createElement('foo');
-
-
- As well, any functions in the C++ API that return string-like
- values, i.e. like DOMStrings and XMLCh arrays, return
- plain vanilla perl-strings in Xerces.pm. This obviates calls
- to "transcode" (in fact, it makes them entirely invalid).
-
- Handling of DOM_NodeList's
- --------------------------
-
- Any function that in the C++ API returns a DOM_NodeList
- (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::DOM_NodeList, 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::DOM_NodeList
- my $node_list_ref = $doc->getElementsByTagName('foo');
-
- # returns a list of XML::Xerces::DOM_Node's
- my @node_list = $doc->getElementsByTagName('foo');
-
- Handling of DOM_NamedNodeMap's
- --------------------------
-
- Any function that in the C++ API returns a DOM_NamedNodeMap
- (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::DOM_NamedNodeMap, just like in C++ API. However, in a list
- context they will return a Perl hash.
- # 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();
-
-Further Examples
-----------------
-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 of the Xerces.pm distribution.
+Handling of DOMString's and XMLCh's
+----------------------------------
+
+Note that the creation of DOMStrings as arguments to to functions is
+optional. That is, where in C++ you'd have to use:
+
+ document.createElement( new DOMString("foo") );
+
+in Xerces.pm, you can use either of:
+
+ $document->createElement( new DOMString('foo') );
+
+or the less cumbersome:
+
+ $document->createElement('foo');
+
+
+As well, any functions in the C++ API that return string-like values,
+i.e. like DOMStrings and XMLCh arrays, return plain vanilla
+perl-strings in Xerces.pm. This obviates calls to "transcode" (in
+fact, it makes them entirely invalid).
+
+Handling of DOM_NodeList's
+--------------------------
+Any function that in the C++ API returns a DOM_NodeList
+(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::DOM_NodeList, 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::DOM_NodeList
+ my $node_list_ref = $doc->getElementsByTagName('foo');
+
+ # returns a list of XML::Xerces::DOM_Node's
+ my @node_list = $doc->getElementsByTagName('foo');
+
+Handling of DOM_NamedNodeMap's
+------------------------------
+
+Any function that in the C++ API returns a DOM_NamedNodeMap
+(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::DOM_NamedNodeMap, just like in C++ API. However, in a
+list context they will return a Perl hash.
+
+ # 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();
+
+
BUGS
====
+
Please send the output of 'perl -V' and a description of your problem
to xerces-p-dev@xml-apache.org. Including a *minimal* example script,
xml file, and/or dtd is helpful. The more time you spend making those
@@ -208,7 +232,12 @@
AUTHORS
=======
+
Tom Watson: Xerces 1.1 port
Harmon Nine and Fredrick Paul Eisele: Xerces 1.3 port
- Jason Stewart: This and that
+ Jason Stewart: Cordination and testing
+
+This list is incomplete. If you feel you were left out please send
+a note to the list (xerces-p-dev@xml-apache.org).
+
---------------------------------------------------------------------
To unsubscribe, e-mail: xerces-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: xerces-cvs-help@xml.apache.org
[prev in list] [next in list] [prev in thread] [next in thread]
Configure |
About |
News |
Add a list |
Sponsored by KoreLogic