EXAMPLE(7libmawk)

💖 EXAMPLE (7libmawk) 💖

okay bestie, this is the libmawk manual and it's literally the "how do I even use this library" page. sit down, hydrate, let's go 🫶

✨ NAME ✨

libmawk-example — the whole vibe of this page: how to use the library 💅

🌸 SYNOPSIS 🌸

#include <libmawk.h>

that's it. that's the entry fee. iconic.

---

🦋 DESCRIPTION 🦋

Libmawk is a library that lets applications embed awk scripts using the code of the popular implementation mawk. no cap, that's the whole point of it.

the normal process is the pipeline, and it goes like this:

1. call libmawk_initialize() to set up a brand new mawk context (with your script(s) loaded) ✨
2. then in the main loop, feed it using libmawk_append_input() 🍓
3. for "out of band" communication, the program may also call functions implemented in awk, and read (or modify) global variables of the awk script 👀
4. the host application usually will also bind some of its own functions to the context using libmawk_register_function — which lets the awk script call the host application's functions directly, as if they were awk builtins or user defined functions. it's giving main character energy fr fr 🔥
5. after the main loop, the application destroys the context, freeing up all the memory allocated for the script(s) 🧚

one context is for one awk program. periodt.

and here's the tea: 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 a different set of awk scripts loaded. these contexts are totally separate, no variables, functions or any sort of states are shared. not one crumb. 🙈

however — the host application may provide means of communication between those scripts, by custom functions or by copying variable contents between them. so they can still gossip, they just need a messenger 💌

---

🎀 Example application 🎀

the following example application creates a single context to demonstrate all the above mentioned functionality. she does it all. she's booked and busy 💅

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

---

💀 bestie quick reality check: if libmawk_initialize hands you back NULL, she did not slay — the example prints libmawk_initialize failed, exiting to stderr and bails with a return of 1. no script, no vibes, just exit.

---

okay that's the whole page, mwah 💋 this was libmawk, dated 2009-08-10, and the manual you just read is EXAMPLE(7libmawk). go forth and embed some awk, bestie — you're gonna eat, no crumbs left 🌈⭐👑💖