The cpphoaf Command-Line Tool
The cpphoafparser Library for the Hanoi Omega-Automata Format (HOAF), version 0.99.2

The cpphoafparser library provides a command-line interface to some of the functionality. This can be roughly divided into two broad areas:

Validating an automaton (no syntax errors, declared properties are correct, ...)
Transforming an automaton (translating from state- to transition-based acceptance, ...)

We assume here that the reader is familiar with the basic concepts of the Hanoi Omega-Automata Format (HOAF).

General

Obtaining and invoking the command-line tool

We assume here that you have downloaded the source code archive from the website. Unpack and build (Linux, OS X, ...):

tar xzvf cpphoafparser-xx.yy.tgz
cd cpphoafparser-xx.yy
make

where xx.yy is the version.

Alternatively, for Windows, you can download a precompiled binary.

There is also a CMakeLists.txt configuration for CMake available. In the top-level directory, execute:

mkdir build
cd build
cmake ../src
make

CMake can alse be used to generate Visual Studio project files.

Getting Help

With

./cpphoaf help

you'll obtain a brief description of the supported commands and flags.

Input / Output

The command-line tool reads the file specified on the command-line, performs the required processing and outputs the result to the standard output. The hyphen character '-' can be used instead of the filename for reading from standard input. Below, we provide some examples of invoking the command-line tool:

In the simplest case, the following command parses the automaton from automaton.hoa and prints the result (the parsed automaton without comments, extra whitespace, etc) to the console:

./cpphoaf print automaton.hoa

In the next example, we pipe the output of some other tool to the input of cpphoaf:

./some-hoa-producer | ./cpphoaf print -

The output can be captured as usual to a file using redirection:

./some-hoa-producer | ./cpphoaf print - > result.hoa

Note: Take care that you do not simultaneously read and write from/to the same file!

Commands and Flags

The general structure of invoking the command line-tool is

./cpphoaf command flag(s) file(s)

Multiple automata

The HOA format supports the streaming of automata, i.e., the ability to represent a sequence of automata in a single file.

Please note that, currently, the cpphoaf tool only supports parsing a single automaton.

Exit value

If you want to use the command-line tool in scripts, the value returned by the tool on exit is useful for diagnosing errors. The tool will return 0 for success/no errors. If there are errors during the processing of the automata, the value 1 will be returned. If there are problems with the invocation (invalid command-line arguments, ...), the value 2 will be returned.

Validating Automata

To check that an automaton in HOA format can be successfully parsed, run

./cpphoaf parse automaton-file.hoa

Parsing OK

If everything went fine, the tool will output that parsing was OK, otherwise there will be an error message indicating what went wrong.

Upon success, the automaton

has been successfully parsed (syntax conforms to the HOA format),
properties specified in the header have been verified to be correct (violations of state-labels, trans-labels, implicit-labels, explicit-labels, state-acc, trans-acc, no-univ-branch, colored are currently detected; for the deterministic and complete properties, violations are currently only detected when implicit transition labels are used),
if an acc-name header has been provided and is one of the standard acceptance conditions specified in the format, the correspondence with the Acceptance header has been verified
the number, ordering and names of the states are valid with regard to the restrictions specified in the HOA format,
if implicit transition labels are used, the required number is present,
alias definitions are non-recursive and all aliases, atomic propositions and acceptance sets that are used are defined.

The semantic validations can be disabled by the command-line option --no-validate. The following command will only check the syntactic correctness according to the HOA format:

./cpphoaf parse --no-validate automaton.hoa

Transforming the Automaton

Pretty-printing the Automaton

The simplest transformation is barely a transformation at all. Via

./cpphoaf print automaton-file.hoa

the automaton is simply parsed and printed back to the standard output.

As comments and superfluous whitespace are ignored by the parser, this transforms the automaton into some kind of canonical form, with the different elements of the HOA format each placed on a single line.

Resolving Aliases

The command-line option --resolve-aliases activates a transformation that (1) removes the Alias: ? definitions and (2) resolves all @alias references in transition labels.

The following command reads the automaton, resolves the aliases and prints the resulting automaton:

./cpphoaf print --resolve-aliases automaton-file.hoa

The option --resolve-aliases can be used with all other commands and options.

Tracing, Implementation Details

If you wish to implement your own transformations or want to use the cpphoafparser library, it might be interesting to play around with the --trace option:

./cpphoaf parse --trace automaton-file.hoa

If activated, tracing will output the sequence of method calls into the HOAConsumer by the parser. This can be used to study the correspondence of syntactical elements in the HOA format and the method calls.

The command-line utility is implemented in the src/cpphoaf.cc. It relies on the various HOAConsumers for the functionality and is a good entry-point for further investigations.

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!

The cpphoaf Command-Line Tool The cpphoafparser Library for the Hanoi Omega-Automata Format (HOAF), version 0.99.2