1   Abstract

SaxMagique is a c++ library that offers an API for creating a saxparser. It is intended to be the simplest way theoretically possible to create a complex saxparser. It is not a replacement of expat or xerces, but an enhancement. In fact, it depends on expat library (could easily be adapted to xerces or others) for which it build-up the [start|end]Element and characters handlers needed.

2   Installation

]$ tar xzvf libsaxmagique-1.0.0.tar.gz
]$ cd libsaxmagique-1.0.0
]$ ./configure
]$ make
]$ sudo make install

]$ ./configure --prefix=/home/username --exec-prefix=/home/username
]$ make
]$ make install

]$ ./configure --with-boost=/usr/local --with-expat=/usr/local

3   SaxMagique API

The principal class of the library is called SaxMagique. The API of SaxMagique calque the API of xsd schema. Indeed, starting from the following xsd schema:

<xs:schema>
  <xs:complexType name="Type_d">
     <xs:attribute name="c" type="xs:integer"/>
  </xs:complexType>
  <xs:complexType name="Type_a">
     <xs:attribute name="b" type="xs:string"/>
     <xs:element name="d" type="Type_d"/>
  </xs:complexType>
  <xs:complexType name="Type_e">
    <xs:complexContent>
      <xs:extension type="a">
        <xs:attribute name="f" type="char"/>
      <xs:extension>
    </xs:complexContent>
  </xs:complexType>
  <xs:element name="rootnode" type="e"/>
</xs:schema>

And the corresponding c++ classes:

class D
{
  int m_c;
public:
  void set_c( int c ) { m_c = c; }
  int get_c() { return m_c; }
};

class A
{
  std::string m_b;
  D m_d;
public:

  void set_b( const std::string& b ) { m_b = b; }
  const std::string& get_b() { return m_b; }
  void set_d( const D& d ) { m_d = d; }
  const D& get_d() { return m_d; }
};

class E : public A
{
  char m_f;
public:
  void set_f( char f ) { m_f = f; }
  char get_f() { return m_f; }
};

The SaxMagique that parse a xml file from this schema and puts the data into corresponding c++ classes is created by:

// Instantiation of the parser

SaxMagique myparser;

// Creation of nodes for the three complexType.
// The nodes are owned by myparser.

saxmagique::ComplexType< D >* ptrNode_D = myparser.complexType< D >();
saxmagique::ComplexType< A >* ptrNode_A = myparser.complexType< A >();
saxmagique::ComplexType< E >* ptrNode_E = myparser.complexType< E >();

// The complexTypes are detailed.

ptrNode_D->attribute( "c", saxmagique::SimpleType< int, Patlac::Atoi >(), &D::set_c );

ptrNode_A->element< D >( "d", &A::set_d )
         ->attribute( "b", saxmagique::SimpleType< std::string >, &A::set_b );

ptrNode_E->extension( ptrNode_D )
         ->attribute( "f", saxmagique::SimpleType< char, Patlac::Atoc() >, &D::set_f );


// The root node is declared.
// A pointer is keeped on this node.
TopLevelElement* ptrTopLevelElement = myparser.topLevelElement( "e", ptrNode_E );

Each line consist only on the minimum: what is the relation ( attribute, element, extension ), what is the marker, what is the corresponding c++ type and to which member function shall it be given.

Now this parser can be use with four lines :

// Set the file to be parsed.
myparser.setFileName( "test.xml" );

// Create a receptable and give it to the parser.
E my_e;
ptrTopLevelElement->assign_object( my_e );

// Parse.
myparser.parse();

4   Is SaxMagique fast?

Yes it's fast, but it could be faster.

• First, take only what you need. If you don't need the element D, to not declare it to the SaxMagique will accelerate parsing.
• Second, avoid "useless" copy of data. Instead of a setter "void set_d( const D& d ) { m_d = d; }" use a setter "D& set_d( const D& d ) { m_d = d; return m_d; }". The SaxMagique will understand and avoid to fill a temporary. If U possess V possess W possess X possess Y possess Z, the temporary for Z may be copied five times!
• Third, there is still amelioration that can be done in the core of the SaxMagique.

5   Related projects

- uniprot

- uniref

- pepXML

- protXML

6   For Contributors

SaxMagique is a complicated machinery that make heavy use advanced c++. The first release of this library is not yet totally contributor friendly, it will slowly tends to become more.

7   Auteur

Copyright 2007 Patrick Lacasse