NAME

       libmawk-example - how to use the library

SYNOPSIS

       #include <libmawk.h>

DESCRIPTION

       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.

Example application

       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;
       }