.\" 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 LIBMAWK_INITIALIZE_STAGE 3libmawk  2009-08-10 "libmawk" "libmawk manual"
.SH NAME
libmawk_initialize_stage* \- create a new libmawk context in 3 stages
.SH SYNOPSIS
.nf
.B #include <libmawk.h>
.sp
.BI "mawk_state_t *libmawk_initialize_stage1(void);
.sp
.BI "mawk_state_t *libmawk_initialize_stage2(mawk_state_t * " m, int " s ", char *" argv[] );
.sp
.BI "mawk_state_t *libmawk_initialize_stage3(mawk_state_t * " m );
.fi
.sp
.SH DESCRIPTION
The
.BR libmawk_initialize_stage* ()
functions together do the same as libmawk_initialize() but allows
the application to take actions between different stages.
.BR libmawk_initialize_stage1 ()
returns a pointer to a newly created libmawk context. Any amount
of libmawk contexts can live in parallel in an application.
.sp
.BR libmawk_initialize_stage2 ()
can be called after a succesful stage1 call.
 Stage2 is responsible for processing the command line arguments and
loading any script.

Arguments are the
same as for a command line mawk session. Scripts are loaded (either from command
line or from files using -f), variables are set (with -v), special options
are set (with -W), etc. Unlike with libmawk_initialize(), the application may
decide not to provide any script at this stage. All command line arguments
are processed.

The most common case is that
the application calls stage1 with no script, then already having a context
makes some manipulations on it (for example registers some C functions that
would be already called in the BEGIN part of the script that will be later
loaded). Optionally before calling stage2 the application loads the actual
script(s) using mawk_append_input_file().
.sp
.BR libmawk_initialize_stage3 ()
is called as a final step of the three-stage initialization process. Stage3
is responsible for running all the BEGIN parts of all scripts loaded at
stage1 or stage2. It is useful to have stage3 in a separate call to allow
applications to manipulate the context right before initializing the scripts.
.sp
Stage2 gets the pointer returned by stage1 and stage3 gets the pointer
returned by stage2. Subsequent calls to libmawk functions should get
the pointer returned by stage3.

.SH "RETURN VALUE"
At stage 1 a pointer to a new libmawk context or NULL on error. Subsequent
stages will return the same pointer or NULL on error.
.SH "SEE ALSO"
.BR libmawk_initialize_stage (3libmawk),
.BR libmawk_uninitialize (3libmawk),
.BR mawk_append_input_file(3libmawk).