example.7libmawk - Man Page

#include <libmawk.h>

Libmawk is a library that lets applications to embed awk scripts using the code of the popular implementation mawk. The normal process is to call libmawk_initialize() to set up a new mawk context (with script(s) loaded), then in the main loop feed it using libmawk_append_input(). For "out of band" communication, the program may also call functions implemented in awk and read (or modify) global variables of the awk script. The hos tapplication usally will also bind some of its functions to the context using libmawk_register_function, which allows the awk script to call the host applicaiton's functions directly as they were awk builtins or user defined functions. After the main loop, the application destroys the context freeing up all memory allocated for the script(s).

One context is for one awk program. One awk program may consist of multiple script files (just as with command line awk, with multiple -f filename arguments). Libmawk is instance safe, the host application may create multiple instances of contexts with the same or with different set of awk scripts loaded. These contexts are totally separate, no variables, functions or any sort of states are shared. However, the host application may provide means of communication between those scripts by custom functions or by copying variable contents between them.

The following example application creates a single context to demonstrate all the above mentioned functionality.

#include <stdio.h>
#include <libmawk.h>

/*
  Purpose: load and run a script using the command
           line syntax of mawk but using a virtual
           stdin buffer instead of the real stdin.
  Run: ./app -f test.awk
*/

int main(int argc, char **argv)
{
  mawk_state_t *m;

  /* init a context, execute BEGIN */
  m = libmawk_initialize(argc, argv);
  if (m == NULL) {
    fprintf(stderr, "libmawk_initialize failed, exiting\n");
    return 1;
  }

  /* feed in some data on the virtual stdin */
  libmawk_append_input(m, "This is a\nmultiline test input\nfor the artificial input buffer.\n");

  /* run the MAIN part of the script as long as
     there's data in the buffer of the virtual stdin */
  libmawk_run_main(m);

  /* run END and free the context */
  libmawk_uninitialize(m);

  return 0;
}