Using the cpphoafparser Library
The cpphoafparser Library for the Hanoi Omega-Automata Format (HOAF), version 0.99.2

The cpphoafparser library can be used to parse and process ω-automata in the HOA format. We assume here that the reader is familiar with the basic concepts of the Hanoi Omega-Automata Format (HOAF).

General Structure

The two main building blocks of the parser library are the parser and classes implementing the HOAConsumer interface. A HOAConsumer has functions corresponding to the various elements that can occur in a HOA automaton. While parsing, the parser calls each of these functions to indicate that this particular element has just occurred.

cpphoafparser is a header-only C++ library, i.e., it suffices to add the include directory to the include path of your compiler and include the corresponding header files. All cpphoafparser elements are contained in the cpphoafparser namespace. It uses C++11 features, so ensure that your compiler is configured to support this standard version.

A Basic Parser

The most basic use of the cpphoafparser library is shown in the following code snippet (src/basic_parser_1.cc):

#include "cpphoafparser/consumer/hoa_consumer_print.hh"
#include "cpphoafparser/parser/hoa_parser.hh"

using namespace cpphoafparser;

/** The most basic HOA parser: Read an automaton from input and print it to the output. */
int main(int argc, const char* argv[]) {
  HOAConsumer::ptr consumer(new HOAConsumerPrint(std::cout));

  try {

    HOAParser::parse(std::cin, consumer);

  } catch (std::exception& e) {
    std::cerr << e.what() << std::endl;
    return 1;
  }
  return 0;
}

Here, the parser reads from std::cin and calls into a HOAConsumerPrint object that just outputs the elements to std::cout.

Chaining Multiple HOAConsumers: HOAIntermediate

The HOAIntermediate class, which itself implements the HOAConsumer interface, provides the basis for chaining multiple HOAConsumers, one after another, each reading the output of the previous one.

Consider the following example (src/basic_parser_2.cc):

#include "cpphoafparser/consumer/hoa_intermediate.hh"
#include "cpphoafparser/consumer/hoa_consumer_null.hh"
#include "cpphoafparser/parser/hoa_parser.hh"

using namespace cpphoafparser;

/* An HOAIntermediate that counts invocations of addState */
class CountStates : public HOAIntermediate {
public:
  typedef std::shared_ptr<CountStates> ptr;
  unsigned int count = 0;

  CountStates(HOAConsumer::ptr next) : HOAIntermediate(next) {
  }

  virtual void addState(unsigned int id,
                        std::shared_ptr<std::string> info,
                        label_expr::ptr labelExpr,
                        std::shared_ptr<int_list> accSignature) override {
    count++;
    next->addState(id, info, labelExpr, accSignature);
  }
};

/** Demonstrating the use of HOAIntermediates */
int main(int argc, const char* argv[]) {
  HOAConsumer::ptr hoaNull(new HOAConsumerNull());
  CountStates::ptr counter(new CountStates(hoaNull));

  try {

    HOAParser::parse(std::cin, counter);
    std::cout << "Number of state definitions = " << counter->count << std::endl;

  } catch (std::exception& e) {
    std::cerr << e.what() << std::endl;
    return 1;
  }
  return 0;
}

We derive CountStates from HOAIntermediate. Its constructor takes the next HOAConsumer in the chain, which can again be a HOAIntermediate. Here, we are passing a HOAConsumerNull object, which does nothing when called, acting as a "no-operation" end of the consumer chain. Inside the CountStates, we override the addState method, which is called for each State: definition in the automaton. We count the number of definitions and pass along the arguments to the next consumer. In the end, we just output the count of the definitions.

The HOAConsumer API

A good starting point for learning about the HOAConsumer API is the documentation of the HOAConsumer interface as well as the rest of the API documentation.

Another good introduction is the source code of the HOAConsumerPrint class, as it translates back from the method calls in the HOAConsumer interface to the textual representation of the HOA format.

Some further tidbits that might be useful:

• The boolean expressions for the explicit transition labels and the acceptance condition are represented by BooleanExpression, with appropriate Atoms for the leaf nodes in the abstract syntax tree. The BooleanExpressions are designed to be immutable. Therefore, subtrees can be safely shared between expressions.
• If you encounter an error inside one of the HOAConsumer method calls, throw an HOAConsumerException.
• Memory managment is generally handled via shared_ptr pointers.
• To trace the method calls into a HOAConsumer or HOAIntermediate, wrap it into a HOAIntermediateTrace object. This will print all the function invocations to the standard output, including the parameters.

If you have further questions, find bugs or want to tell us about your use of the cpphoafparser library, please feel free to contact us!

(c) 2015-2016 Joachim Klein <klein@tcs.inf.tu-dresden.de>, David Müller <david.mueller@tcs.inf.tu-dresden.de>