SAX Parser
Prev | Chapter 2. Parsers | Next

## SAX Parser

The SAX (Simple API for XML) parser presents each node of the XML document in sequence. So when you process one node, you must have already stored information about any relevant previous nodes, and you have no information at that time about subsequent nodes. The SAX parser uses less memory than the DOM parser and it is a suitable abstraction for documents that can be processed sequentially rather than as a whole.

By using the `parse_chunk()` method instead of for instance `parse_file()`, you can even parse parts of the XML document before you have received the whole document.

As shown in the example, you should derive your own class from SaxParser and override some of the virtual methods. These "handler" methods will be called while the document is parsed.

### Example

This example shows how the handler methods are called during parsing.

Source Code

File: `myparser.h`

    #ifndef __LIBXMLPP_EXAMPLES_MYPARSER_H
    #define __LIBXMLPP_EXAMPLES_MYPARSER_H

    #include <libxml++/libxml++.h>

    class MySaxParser : public xmlpp::SaxParser
    {
    public:
      MySaxParser();
      ~MySaxParser() override;

    protected:
      //overrides:
      void on_start_document() override;
      void on_end_document() override;
      void on_start_element(const Glib::ustring& name,
                                    const AttributeList& properties) override;
      void on_end_element(const Glib::ustring& name) override;
      void on_characters(const Glib::ustring& characters) override;
      void on_comment(const Glib::ustring& text) override;
      void on_warning(const Glib::ustring& text) override;
      void on_error(const Glib::ustring& text) override;
      void on_fatal_error(const Glib::ustring& text) override;
    };

    #endif //__LIBXMLPP_EXAMPLES_MYPARSER_H

File: `main.cc`

    #ifdef HAVE_CONFIG_H
    #include <config.h>
    #endif

    #include <fstream>
    #include <iostream>
    #include <stdlib.h>
    #include <cstring> // std::memset()

    #include "myparser.h"

    int
    main(int argc, char* argv[])
    {
      // Set the global C and C++ locale to the user-configured locale,
      // so we can use std::cout with UTF-8, via Glib::ustring, without exceptions.
      std::locale::global(std::locale(""));

      std::string filepath;
      if(argc > 1 )
        filepath = argv[1]; //Allow the user to specify a different XML file to parse.
      else
        filepath = "example.xml";

      // Parse the entire document in one go:
      auto return_code = EXIT_SUCCESS;
      try
      {
        MySaxParser parser;
        parser.set_substitute_entities(true);
        parser.parse_file(filepath);
      }
      catch(const xmlpp::exception& ex)
      {
        std::cerr << "libxml++ exception: " << ex.what() << std::endl;
        return_code = EXIT_FAILURE;
      }

      // Incremental parsing, sometimes useful for network connections:
      try
      {
        std::cout << std::endl << "Incremental SAX Parser:" << std::endl;

        std::ifstream is(filepath.c_str());
        if (!is)
          throw xmlpp::exception("Could not open file " + filepath);

        char buffer[64];
        const size_t buffer_size = sizeof(buffer) / sizeof(char);

        //Parse the file:
        MySaxParser parser;
        parser.set_substitute_entities(true);
        do
        {
          std::memset(buffer, 0, buffer_size);
          is.read(buffer, buffer_size-1);
          if(is.gcount())
          {
            // We use Glib::ustring::ustring(InputIterator begin, InputIterator end)
            // instead of Glib::ustring::ustring( const char*, size_type ) because it
            // expects the length of the string in characters, not in bytes.
            Glib::ustring input(buffer, buffer+is.gcount());
            parser.parse_chunk(input);
          }
        }
        while(is);

        parser.finish_chunk_parsing();
      }
      catch(const xmlpp::exception& ex)
      {
        std::cerr << "Incremental parsing, libxml++ exception: " << ex.what() << std::endl;
        return_code = EXIT_FAILURE;
      }

      return return_code;
    }

File: `myparser.cc`

    #include "myparser.h"
    #include <glibmm/convert.h> //For Glib::ConvertError

    #include <iostream>

    MySaxParser::MySaxParser()
      : xmlpp::SaxParser()
    {
    }

    MySaxParser::~MySaxParser()
    {
    }

    void MySaxParser::on_start_document()
    {
      std::cout << "on_start_document()" << std::endl;
    }

    void MySaxParser::on_end_document()
    {
      std::cout << "on_end_document()" << std::endl;
    }

    void MySaxParser::on_start_element(const Glib::ustring& name,
                                       const AttributeList& attributes)
    {
      std::cout << "node name=" << name << std::endl;

      // Print attributes:
      for(const auto& attr_pair : attributes)
      {
        try
        {
          std::cout << "  Attribute name=" <<  attr_pair.name << std::endl;
        }
        catch(const Glib::ConvertError& ex)
        {
          std::cerr << "MySaxParser::on_start_element(): Exception caught while converting name for std::cout: " << ex.what() << std::endl;
        }

        try
        {
          std::cout << "    , value= " <<  attr_pair.value << std::endl;
        }
        catch(const Glib::ConvertError& ex)
        {
          std::cerr << "MySaxParser::on_start_element(): Exception caught while converting value for std::cout: " << ex.what() << std::endl;
        }
      }
    }

    void MySaxParser::on_end_element(const Glib::ustring& /* name */)
    {
      std::cout << "on_end_element()" << std::endl;
    }

    void MySaxParser::on_characters(const Glib::ustring& text)
    {
      try
      {
        std::cout << "on_characters(): " << text << std::endl;
      }
      catch(const Glib::ConvertError& ex)
      {
        std::cerr << "MySaxParser::on_characters(): Exception caught while converting text for std::cout: " << ex.what() << std::endl;
      }
    }

    void MySaxParser::on_comment(const Glib::ustring& text)
    {
      try
      {
        std::cout << "on_comment(): " << text << std::endl;
      }
      catch(const Glib::ConvertError& ex)
      {
        std::cerr << "MySaxParser::on_comment(): Exception caught while converting text for std::cout: " << ex.what() << std::endl;
      }
    }

    void MySaxParser::on_warning(const Glib::ustring& text)
    {
      try
      {
        std::cout << "on_warning(): " << text << std::endl;
      }
      catch(const Glib::ConvertError& ex)
      {
        std::cerr << "MySaxParser::on_warning(): Exception caught while converting text for std::cout: " << ex.what() << std::endl;
      }
    }

    void MySaxParser::on_error(const Glib::ustring& text)
    {
      try
      {
        std::cout << "on_error(): " << text << std::endl;
      }
      catch(const Glib::ConvertError& ex)
      {
        std::cerr << "MySaxParser::on_error(): Exception caught while converting text for std::cout: " << ex.what() << std::endl;
      }
    }

    void MySaxParser::on_fatal_error(const Glib::ustring& text)
    {
      try
      {
        std::cout << "on_fatal_error(): " << text << std::endl;
      }
      catch(const Glib::ConvertError& ex)
      {
        std::cerr << "MySaxParser::on_characters(): Exception caught while converting value for std::cout: " << ex.what() << std::endl;
      }
    }

Prev | Up | Next
Chapter 2. Parsers | Home | TextReader Parser