noble (7) example.7libmawk.gz

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