qse/ase/awk/awk.man

.title Introduction To XPAWK

== OVERVIEW ==

=== What is it? ===
'''''XPAWK''''' is an embeddable implementation of the AWK programming language. It is composed of a set of C functions to help programmers embed the AWK interpreter to their own applications easily. 

=== What does it do? ===
'''''XPAWK''''' can do most of the things that other existing AWK interpreters can do. <TODO:>

=== Differences with other implementations ===
There exist a number of AWK interpreters available. Most of Unix/Linux operating systems come with an AWK interpreter. <TODO:>

== DESCRIPTION ==

=== Interpreter ===
Multiple instances of interpreters can be created in a single application and each instance of the interpreter created maintains its own state in the data structure pointed at by its handle of the type ''xp_awk_t''.

 * xp_awk_t - an abstract type to an interpreter object.
 * xp_awk_open - creates an interpreter object.
 * xp_awk_close - destroys the interprer object created by xp_awk_open.

{{{
xp_awk_t* xp_awk_open (void);
void xp_awk_close (xp_awk_t* awk); 
}}}

The interpreter provides two distinct functionalites in large; the parser and the executor. The parser transforms the source code into the internal parse tree and the executor evaluates the parse tree and runs the code.

{{{
int xp_awk_parse (xp_awk_t* awk);
int xp_awk_run (xp_awk_t* awk, xp_awk_io_t txtio, void* txtio_arg); 
}}}

=== IO Handlers ===
'''''XPAWK''''' does not provide any built-in IO handling routines. Instead, it requires users to provide them. 4 different IO streams should be provided to take full advantage of the interpreter.

 * Source code input
 * Source code output
 * Data input
 * Data output

{{{
enum 
{
	XP_AWK_INPUT_OPEN   = 0,
	XP_AWK_INPUT_CLOSE  = 1,
	XP_AWK_INPUT_NEXT   = 2,
	XP_AWK_INPUT_DATA   = 3,

	XP_AWK_OUTPUT_OPEN  = 4,
	XP_AWK_OUTPUT_CLOSE = 5,
	XP_AWK_OUTPUT_NEXT  = 6,
	XP_AWK_OUTPUT_DATA  = 7
};

typedef xp_ssize_t (*xp_awk_io_t) (int cmd, void* arg, xp_char_t* data, xp_size_t count);
}}}

=== Miscellaneous Functions ===
'''''XPAWK''''' provides extra utility routines as well as the interpreter. These routines used by the interpreter can be accessed from the interested applications directly without regard to the interpreter.

==== String ====

==== Conversion ====
 * xp_awk_strtolong - convert a numeric string to an integer of the xp_long_t type. 
 * xp_awk_strtoreal - convert a numeric string to a decimal number of the xp_real_t type.

{{{
xp_long_t xp_awk_strtolong (const xp_char_t* str, int base, const xp_char_t** endptr); 
xp_real_t xp_awk_strtoreal (const xp_char_t* str); 
}}}

==== Regular Expression ====
The regular expression routines built into the interpreter can replace other regular expression libraries available. By utilizing this, the application can have the identical regular expression functionalities as the embedded AWK interpreter.

{{{
xp_awk_rex_t* xp_awk_rex_open (xp_awk_rex_t* rex);
void xp_awk_rex_close (xp_awk_rex_t* rex);
}}}

=== User-defined Built-in Functions ===
Custom built-in functions can be added to the interpreter. This requires the deeper look into the internals of the interpreter.

== EXAMPLE ==
{{{
#include <xp/awk/awk.h>

int xp_main ()
{
	return 0;
}
}}}