.\" Copyright 2009 Tibor Palinkas (mawk@inno.bme.hu)
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.TH EXAMPLE 7  2009-08-10 "libmawk" "libmawk manual"
.SH NAME
libmawk example \- how to use the library
.SH SYNOPSIS
.nf
.B #include <libmawk.h>
.sp
.SH DESCRIPTION
Libmawk is a library that lets applications to embed awk scripts using the
code of the popular implementation
.B 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).
.sp
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.
.SH Example application
The following example application creates a single context to demonstrate
all the above mentioned functionality.
.nf
.fi