SWIG XML - Generating XML from SWIG

• Introduction -- What It Does

• Installing and Building

• How to Use the Generated XML

• Extending and modifying swigxml

Introduction -- What It Does

swigxml is a SWIG extension that enables SWIG to generate XML.

What is it good for? Here are several suggestions:

• Wrapper generator -- Suppose that you want to write wrappers that are slightly different from those that standard SWIG generates or you want to generate wrappers for a target language that SWIG does not support and you want to implement this generator in your favorite language (Python, for sure). Generating XML from SWIG will enable you to do this.
• Static source code analysis -- Since the generated XML describes the interface to library of classes and functions, that generated XML could be the input to programs that do an analysis of that (static) interface.
• Reporting -- Applications could be implemented to create reports that describe the interface exposed by a class or function library.

What is included?

• xml.h and xml.cxx -- The source files that implement the extension.
• swigmain.cxx -- A replacement for Source/Modules1.1/swigmain.cxx. This replacement adds the hook to generate XML and adds a line to the usage message.
• Makefile.patch -- A patch file that tells you how to modify Source/Modules1.1/Makefile
• swigxml.py -- A Python module that will parse the generated XML output and populate a tree of Python data structures (instances of classes defined in swigxml.py). If you intend to implement processors for the generated XML in Python, this is something you might want to look at.
• swigxml.xsd -- An XML Schema description of the output generated by swigxml. This was used as input to generateDS.py to produce swigxml.py. If you extend swigxml (i.e. you modify xml.cxx to produce additional output), you may want to update swigxml.xsd.
• swigxml.html -- This documentation.

Installing and Building

Follow these steps:

1. Down-load the CVS development version of SWIG. You can find instructions at http://www.swig.org/cvs.html. You will need to run the "autogen.sh" before doing "./configure;make". See the note about autogen.sh in the SWIG README file.
2. Build SWIG.
3. From the root of the SWIG directory, unroll swigxml. Note that this replaces the file Source/Module1.1/swigmain.cxx. I've also provided a patch file (swigmain.patch) in case you want to patch or edit swigmain.cxx instead of replacing it.
4. Modify the Makefile in Source/Modules1.1 -- Add xml.o to the variable OBJS and add xml.cxx to the variable SRCS. Here is a diff that should show you what to do:

   ##############################################################################
   *** Makefile    Mon Mar 18 14:15:05 2002
   --- tmp Sat Mar 23 09:38:36 2002
   ***************
   *** 13,20 ****
     RANLIB   = ranlib
   
     TARGET   = libmodules11.a
   ! OBJS     = main.o emit.o lang.o typepass.o allocate.o browser.o contract.o sw
   ! SRCS     = main.cxx emit.cxx lang.cxx typepass.cxx allocate.cxx browser.cxx c
   
     INCLUDE  = -I$(srcdir)/../Include             \
                -I$(srcdir)/../DOH/Include         \
   --- 13,20 ----
     RANLIB   = ranlib
   
     TARGET   = libmodules11.a
   ! OBJS     = main.o emit.o lang.o typepass.o allocate.o browser.o contract.o sw
   ! SRCS     = main.cxx emit.cxx lang.cxx typepass.cxx allocate.cxx browser.cxx c
   
     INCLUDE  = -I$(srcdir)/../Include             \
                -I$(srcdir)/../DOH/Include         \
   ##############################################################################
   

5. Build SWIG, again.
6. Now, when you run the new swig executable with the "-help" option. You should now see the following line at the end of the list of "Target Language Options:"

           -xml            - Generate XML description doc.
   

You should now be able to generate XML output (and optionally pipe it to a file) with something like the following:

        swig -xml -c++ myclass.i > myclass.xml

How to Use the Generated XML

In order to use the generated XML, you will need to write an application.

Python is an excellent language for writing XML applications.

A good place to start in writing that application in Python is with swigxml.py, which comes with the swigxml distribution.

Here is a simple test of swigxml.py -- It parses a file containing XML output from SWIG, creates a tree of instances of Python classes, then exports the stdout:

        python swigxml.py myclass.xml

So, a reasonable next step is to make a copy of swigxml.py, then modify the classes in it until they do what you need. If you need to walk the tree of objects, consider copying, renaming, and modifying the export method in each of the data representation classes.

Extending and modifying swigxml

swigxml itself is implemented as an extension to SWIG. So, in order to extend my extension, you just keep on doing what I was doing in implementing swigxml.

Here is where to look:

• Source/Modules1.1/xml.h -- Contains the class definition for the C++ class that generates XML.
• Source/Modules1.1/xml.cxx -- Contains the implementation of the XML generation class.
• Source/Modules1.1/swigmain.cxx -- Contains (1) an addition to the help/usage message displayed by SWIG and (2) a handler for the "-xml" option.

The SWIG1.3 Development Documentation contains a bit of help on how to write extensions to SWIG and more is promised for the future. You can find this documentation at http://www.swig.org /Doc1.3/Extending.html

If you make significant additions to the generated output (e.g by modifying xml.cxx), then you may want to consider modifying the data structure definitions in swigxml.xsd and re-generating swigxml.py (or something to replace it). In order to do so, edit swigxml.xsd, then run generateDS.py (also described at http://www.rexx.com/~dkuhlman). Something like the following should do it:

        python generateDS.py swigxml.xsd > my_new_swigxml.py