C++ Interface

Applications may want to integrate Soufflé programs as a library rather than as a stand-alone tool. For this purpose, we have developed a C++ interface to call Soufflé programs.

With the option -g <name>.cpp a C++ class is generated for a Soufflé program that can be directly embedded in another C++ application. The generated class may have several instances. An instance provides interfaces to populate input relations, to run the program, and to retrieve data from the output relations. Note that the generated class is required to be compiled with the flag __EMBEDDED_SOUFFLE__ to disable the default main() function of a Soufflé program.

An instance of a Soufflé program can be generated by executing the following code:

 #include "souffle/SouffleInterface.h"

 if(souffle::SouffleProgram *prog=souffle::ProgramFactory::newInstance("<name>")) {
  /* populate input relations */
  /* run a program */
  /* retrieve data from output relations */
  delete prog;
 } else { 
  std::cerr << "Failed to create instance for program <name>\n";
  exit(1);       
 } 

Populate Input Relations

Data of input relations may be read from CSV files. This functionality is executed by invoking the code

 prog->loadAll("<dir>"); 

The directory <dir> represents the input directory where the input files of the relations are located. Alternatively, the data can be pushed into the input relations by using the insert() method.

 // get relation reference 
 if(souffle::Relation *rel = prog->getRelation("<rel-name>")) {
   
   // create  tuple for the relation
   souffle::tuple newTuple(rel); 

   /// place integers / symbols into the relation using << operator
   newTuple << "TestData" << 10; 

   // insert tuple into relation <rel-name>
   rel->insert(newTuple);

 }

Run the program

A Soufflé program is executed invoking the run() method, e.g..,

 #include "souffle/SouffleInterface.h"

 if(souffle::SouffleProgram *prog=souffle::ProgramFactory::newInstance("<name>")) {
  prog->loadAll("."); // load from current directory
  prog->run(); // run catalog program
  /* retrieve data from output relations */
  delete prog;
 } else { 
  std::cerr << "Failed to create instance for program <name>\n";
  exit(1);       
 } 

Retrieve output relations

Output relations can be accessed via the container provided by the relation. The current tuple provides stream operators to write data into variables.

     if(souffle::Relation *rel = prog->souffle::getRelation("<my-rel>")) {
          for(auto &output : *rel ) {
               output >> var1 >> var2;
            }
      } 

Alternatively, the method prog->printAll() writes the contents of the output relations to their defined destinations.